Standardising code documentation
Win
created: 2006-05-02 10:36:18
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?
Re: Standardising code documentation
created: 2006-05-02 10:42:05
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.
Re: Standardising code documentation
created: 2006-05-02 11:00:41

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.
Re^2: Standardising code documentation
Win
created: 2006-05-02 11:15:22
My objectives for this are a follows. To speed documentation write ups and to increase quality of writeups. If people are already familiar with the ontology, a standardised list could help readers digest the documentation. With these objectives in mind I think that some of the other factors such as coding time would not need to be included. Although, having said that, I agree that it could be useful for readers to see how the coder had justified the expense of producing the code and a similar justification could be used by the reader to further the work or not.
Re: Standardising code documentation
created: 2006-05-02 11:08:04
You may check POD Standards, which contains an extensive discussion and many interesting ideas...
Re: Standardising code documentation
created: 2006-05-02 22:14:10
... 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.

perlmonks.org content © perlmonks.org and blazar, graff, jdporter, kudra, Win

prlmnks.org © 2006 edmund von der burg (eccles & toad)

v 0.03