Slashdot Mirror
Comments On Code Comments?
theodp writes "It seems like comments are on programmers' minds these days. The problem with comments, as Zachary Voase sees it, is that our editors display comments in such a way as to be ignored by the programmer. And over at Scripting News, Dave Winer shares some comments on comments, noting how outlining features allow programmers to see and hide comments as desired. 'The important thing is that with elision (expand/collapse),' explains Winer, 'comments don't take up visual space so there's no penalty for fully explaining the work. Without this ability there's an impossible tradeoff between comments and the clarity of comment-free code.' Winer also makes the case for providing links in his code to external 'worknotes.' So, what are your thoughts on useful commenting practices or features, either implemented or on your wishlist?"
I was very amused when Donald Knuth announced Literate Programming, since I'd been doing something quite similar for years, although there weren't any automated tools back then.
First I wrote WHAT the function was supposed to do. This was the comments.
Then, I wrote the code to DO it.
If I did the job right - and kept the comments up to date (people really manage to do that?), then when I came back to make fixes or improvements, I'd know what the code was doing and what the likely consequences of changing it could be. Including the less obvious ones, such as things that depended on subsidiary routines.
I have extra incentive to write good comments these days. Back then, major systems often had program logic manuals. These days, the apps are more complex, but the time to sit down and write a PLM is rarely there. However, if the comments were well-done, tools like Oxygen and Javadoc can generate a fairly decent substitute.