Mike Gunderloy and Jeff Langr present their take on commenting in the code. I have seen extremes where some comment every single line of code and others who believe that writing any non-code is a waste of time and effort. Mike has categorized comments that can help you to decide whether you need to comment or not.
So if code needs comments, but not all comments are good, how do you write good comments? In general, there are at least four kinds of comments that I think are worthwhile in most source code:
- Placeholder comments
- Summary comments
- Intent comments
- Rocket Science comments
I believe in writing simple code, that is self explanatory and does not need comments. So, where do I use comments? I use comments for something that probably the intent comments overlaps with. Usually, the code represents a solution, not the problem. Comments can be effectively used to communicate the problem to the reader. I use comments to complete the code, complete the solution with the problem it is supposed to solve. I have been pleasantly surprised that it not only helps when someone else picks up your code ages later, but also while reviewing and testing.
February 23rd, 2007 at 8:21 am
I love the new blog look! Wow.
And I totally agree with you about comments. Still, in code that gets distributed and used by the general public, like WordPress Themes, sections of code specific to the Theme or different from typical Themes needs to be added. I always add a comment code to name each template, which helps me with testing later to know which templates are being used in a generated web page. Sometimes I use two or more sidebars in a Theme, depending upon the page view. When I look at the generated code for a page, I want to know if this is using sidebar1 or sidebar3.
Simple stuff but it helps me while I’m working on it, and then two years later when I can’t remember what I did and have to make changes. The sidebar2 reminds me that I used more than one sidebar in this Theme.
Memory is a fleeting thing and comments really help.
February 23rd, 2007 at 8:27 pm
Thanks for the post and link to the article.
All I ask is that developers question the existence of each comment, and if there’s a better way to express it in code, do so. The comments left over after this process are probably fine.
I agree that comments can help memory. So can unit tests–those are generally what I use to refresh my memory about specifics (but that also requires a cleaner design).
February 24th, 2007 at 5:05 am
Lorelle, I am glad you liked the theme. Comments can help remember the specifics.
Jeff, I agree with you that existence of each comment should be questioned. Comments should not be used everywhere, they make the code feel less important
Unit tests can do a lot of things, however, it really depends on the developer’s will to be consistent with them. More often than not I have found that developers’ enthusiasm about unit tests decreases with increasing pressure and a closer deadline.
June 4th, 2007 at 8:34 pm
November 1st, 2007 at 11:36 am
[...] lot of programmers feel that comments are not necessary, but I find a place for them in explaining the problem the code is trying to solve. Another place where documentation can be useful is to record rationale [...]
December 28th, 2007 at 2:16 am
The literate programming way that I am trying to adopt lies heavily on comments, but it also replaces the separate documentation… docs too.
March 13th, 2008 at 12:05 am
[...] is not evil. I document to record rationale behind certain decisions or to document the problem that the code solves. There might be cases where you are building an API and you want to document it to save someone the [...]