[Dirvish] Comments in Dirvish

Doug Hanks 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
pointless.

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
is enough.

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
were made.

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 mailing list