For many programmers, documenting their code is a chore, yet every piece of code that's going to be (re)used needs both instructions for the user, and adequate explanation of techniques for the code maintainer. The need for BOTH of these forms of support documentation is often overlooked by the newcomer, but that's really a subject for another day ...

In some languages such as Perl, you can write code that's crystal clear, easy to follow, and has the artistic beauty of a Rembrandt. And you can also write code that makes a dog's dinner look pretty. It's up to the development team and their managers to set coding styles and standards - see our sample standards document for an example of what's good and bad practise. Then in Perl you can use POD (Plain Old Documentation) to provide your user docs.

Python is particularly clever in that it forces certain good practise on the programmer, yet without imposing the need for extra levels of declaration. And it does this by using simple techniques such as the indented block structure. example.

When I first came to Python (I admit it), I swore and cursed at the need to inset blocks! But I've learn just how clever that structure really is. You loose a rats nest of { and } characters (and there's no "done", "endif" or "fi" either) and you gain a layout where you can very clearly see which code goes with which conditional statement. Try it once, and you'll hate it. Try it three times, and you'll love it and never want to go back to the bad old ways. And it helps make you code self documenting with that documentation remaining up to date with code changes.

On the user documentation side too, Python has some great tools. Documentation strings allow you to provide structured documentation with each module and each defined function or method, and that documentation can be explored with automated tools such as pydoc. Whether you're writing classes to be called by other programmers, or top level applications, you'll be thanked a thousand times over by your users even if they don't actually email you to say it. Oh - and with documentation strings, the instructions remain in the same file as the source so that they won't get lost at the point of distribution!
(written 2006-04-04 07:02:05)

 P306 - Perl - Plain Old Documentation
P711 - An Introduction to Standards in Perl
Y103 - Python - Conditionals and Loops
Y105 - Python - Functions, Modules and Packages
Y116 - Python - Best Programming Practice

Back to Well House Manor goes ahead

Previous and next or Horse's mouth home

Forward to The best Open Source library in town

Keeping your regular expressions simple
Both ends of the animal
Architectural Heritage - Devizes
The best Open Source library in town
Python - block insets help with documentation
Well House Manor goes ahead
Database design - get it right from first principles
PHP Image viewing application
Ruby course - oops - it's not happening
Python to MySQL