Standardising code documentation

Win has asked for the wisdom of the Perl Monks concerning the following question:

I am in the process of writing documentation for some of my code. I am trying to standardise the documentation as much as possible so that similar points are included in each program. One of the lists that I want to standardise is the ‘motivation for creating a distinct program in a process that uses a cluster of Perl programs’. I believe that many code documenters could use this list. To achieve this I will need comment from others. The motivations that I was thinking of including are:

a) To ease viewing of code.
b) To allow multiple process paths to be run at once.
c) To create a distinct process for which the code is frequently updated.
d) To create a distinct process for which the code is infrequently updated.
e) To create conditions to be placed on the system call eg. CPU usage.
f) To break code so processes can be retrieved from multiple directory locations or physical drives.
g) To make use of differential file access privileges.

There may be many reasons for breaking up a single piece of code of course. Can people think of other reasons? Also, is this exercise worthwhile?

Comment on Standardising code documentation

Replies are listed 'Best First'.
Re: Standardising code documentation by kudra (Vicar) on May 02, 2006 at 14:42 UTC
It's easier to test smaller components, and there are also other situations where you might want to run just a subset of a larger process (for instance if you had a script which fetched a file, parsed it and inserted it in the database, you might want to just parse and insert it if the fetch succeeded and the parse failed). Of course command-line switches can be used limit operations as well.	[reply]
Re: Standardising code documentation by blazar (Canon) on May 02, 2006 at 15:08 UTC
You may check POD Standards, which contains an extensive discussion and many interesting ideas...	[reply]
Re: Standardising code documentation by jdporter (Chancellor) on May 02, 2006 at 15:00 UTC
You seem to have good engineering intentions with this. So I will say that for that purpose it doesn't quite go far enough. Rather than simply say "why I did this", a programmer should document the entire decision process, including at least the factors that went into the decision and the evaluations. Essentially, the cost/benefit analysis. The risks, the trade-offs. Otherwise, with what you have, you may as well simply insert a standard header on each program that says "This is a separate program for all the usual reasons." We're building the house of the future together.	[reply]
A reply falls below the community's threshold of quality. You may see it by logging in.
Re: Standardising code documentation by graff (Chancellor) on May 03, 2006 at 02:14 UTC
... is this exercise worthwhile? Providing documentation is usually worthwhile, but the important thing about documentation is to make it as useful, informative, and succinct as possible for the intended reader. I would be wary of equating "standardized" with "useful to the reader", especially if "standardized" means you have an extended number of slots to fill no matter what (like "motivation for X"). Some notion of slots is very useful, like: Name, Synopsis, Description, Author, and similar 'standard man page' categories -- along with conventions like: for a command-line tool, Synopsis shows all possible command line options and args, and Description provides an explanation for each; Description covers relevant features of input and output; etc. If the motivation for something is really significant, this would be explained in the course of the Description section (e.g. when it's appropriate to use this tool rather than some other tool, etc). But sometimes the motivation is likely to be irrelevant or self-evident, and there's no point filling a slot with useless fluff just because you need to put something in that slot. Having to fill the slot with a pre-cooked phrase chosen from a closed set has the potential of making it even more meaningless. Do you write the documentation before writing the code? It would be good if you did -- such initial documentation should be treated as the specification that the code should satisfy, and is likely to help focus the process of actually writing the code. It's harder to write docs for code that has already been written and lacks docs.	[reply]


There's more than one way to do things
	PerlMonks