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.
In reply to Re: Standardising code documentation
by graff
in thread Standardising code documentation
by Win
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |