Quotes of the week - all about documentation

Posted Dec 11, 2008 18:35 UTC (Thu) by iabervon (subscriber, #722)
In reply to: Quotes of the week - all about documentation by hppnq
Parent article: Quotes of the week - all about documentation

I think the common issue is that people document things that don't need to be documented until they burn out on doing useless work, and finally get to something that needs to be documented and don't document it.

The reality is that almost all code, most functions, and some variables don't need to be documented. Many cases of needing documentation are actually maintainability flaws (i.e., people who don't read the documentation, which is most people most of the time, will write code with bugs). And it's important to avoid providing obvious documentation, because it makes it harder to realize that something is actually tricky. But there's a tendency to strive for completeness and then fail in arbitrary ways.

Of course, the best documentation is generally not written by the author of the code, but by the first person to have problems understanding it and then figure it out.

Quotes of the week - all about documentation

Posted Dec 11, 2008 21:44 UTC (Thu) by stijn (subscriber, #570) [Link] (2 responses)

Seconded, with some additional thoughts. I often write code initially with few comments, pertaining to design or gotchas or ideas for improvement where necessary. Then when I go in a few months later and try to find the logic behind it all, because a bug needs fixing or functionality added, or because the code needs to be generally modularized and sanitized, I usually add much more extensive documentation. It helps at that point to be both the author of the code and to experience puzzlement. As a method (not suitable for all projects) it works quite well for me, although I would rather not submit the result as a good example of how to document code. Still, I think the best annotation comes from a second pass over the code, by someone not actively working on it. This might explain its scarcity. I also think that good documentation largely describes data structures, their invariants, the range of states they may assume, and what bits of code do to achieve transformations and maintain invariants. Don't show flowcharts ..

Quotes of the week - all about documentation

Posted Dec 11, 2008 22:22 UTC (Thu) by marduk (subscriber, #3831) [Link] (1 responses)

That works until you write something and then immediately get put on another project or part of the code, then someone else gets your code and makes more undocumented changes and again and again. Eventually your code comes back your way and you're like... wtf?

Quotes of the week - all about documentation

Posted Dec 12, 2008 10:25 UTC (Fri) by stijn (subscriber, #570) [Link]

It was merely an observation. Additionally, your scenario was already included in my description. If I am the second developer getting the first developer's code, I would definitely add comments as I went in. So, I am advocating this as a good habit to follow at a personal level rather than as project documentation guidelines.

Quotes of the week - all about documentation

Posted Dec 12, 2008 17:51 UTC (Fri) by hppnq (guest, #14462) [Link]

Some projects of course have very strict guidelines as to what is accepted in code and comments. I don't think that these are counterproductive, in general. From what I remember about the Apache code -- we're talking 1999 here ;-) -- every routine was nicely documented at the top but the code did not have too many comments interspersed. It worked like a charm, I think, and many projects utilize a similar strategy.

I think the documentation effort should be geared more towards such a situation than one in which each bit of code is properly documented: that is, indeed, quite a waste of time and energy. It can never be wrong to document what a well-defined part of a bigger picture does (so this should be the rule), whereas documenting bits and pieces has to be indicative of problems in the code (so this should be the exception). I would therefore say that maintainers have a special interest and responsibility when it comes to documentation.

Quotes of the week - all about documentation

Posted Dec 12, 2008 20:00 UTC (Fri) by droundy (subscriber, #4559) [Link]

Of course, the best documentation is generally not written by the author of the code, but by the first person to have problems understanding it and then figure it out.

And the worst documentation is written by the first person have problems understanding the code, and try to figure it out, but fail... which I've seen happen on more than one occasion with code I wrote. :(