[Dirvish] Comments in Dirvish
dhanks at gmail.com
Wed Dec 15 16:14:45 PST 2004
Comments should add something that is not immediately evident from the
code, or collect into one place information that is spread through the
source. When something subtle is happening, a comment may clarify,
but if the actions are obvious already, restating them in words is
A comment that introduces each function sets the stage for reading the
code itself. If the code isn't too long or technical, a single line
Sometimes code is genuinely difficult, perhaps because an algorithm is
complicated or the data structures are intricate (read perl). In that
case, a comment that points to a soruce of understanding can aid the
reader. It may also be valuable to suggest why particular decisions
Don't belabor the obvious
Comment functions and global data.
Don't comment bad code, rewrite it.
Don't contradict the code.
This is why I feel Dirvish doesn't contain a lot of comments.
- Doug Hanks = dhanks(at)gmail(dot)com
More information about the Dirvish