Perl Programming/Exercise 4

Documenting your program

Using a technique called "Plain old Documentation" (POD), take one of your Perl programs, and write about what it does, how it works, and what options it accepts. You will need to write the documentation in the same file as the Perl program, using the special POD markup language [1]

Check that your program still runs correctly with the documentation embedded in it.

Using the pod2text tool, create a text-file help file for your program, and check that it's nicely formatted and easy to read. (You will need to run a conversion program to extract the documentation from your program into a text-file)

Creating HTML documentation

Using the POD toolkit, extract the documentation from your Perl program into an HTML file. Open the HTML file with your browser and check it's nicely formatted and easy to read.

If you like to use LaTeX or man, try compiling your documentation as LaTeX or Troff files, respectively.

Writing a test-suite

Find a testing framework which will allow you to write tests for your Perl program, to automatically test its functionality. Taking a complex program from a previous exercise, write tests which check for correct behaviour in each part of your program.

Insert a deliberate error in the program being tested, and check that the error is spotted by the test-suite. See whether you can make the program display incorrect results and still pass the test-suite. (if so, modify the test-suite to detect this incorrect version of the program)

Re-write the program from scratch using a different method for some of the functions. Check that the new program passes your test-suite.

Putting it all together

Write a program which scans a Perl script and displays the size of the program, the number of comments, and calculates the density of the program (number of statements divided by lines of code)

Display the value of the program by looking-up an estimate of how much it costs per line of code to develop a program in industry.

Display the estimated number of errors in the program by looking-up the expected number of errors per thousand lines of code for an average program.

Write the documention and test-suite for your new program.

Download a random perl script from the internet, and see how it matches up on your code-quality meter.

Answers

Previous exercise | Next exercise