Comments are an invaluable tool designed to communicate what is otherwise incomprehensible. If I come behind you, I’ll be cranky because I have no idea what the Newton-Raphson approximation, and you didn’t bother to make a comment on the subject.
Sometimes we have to write highly complex code, and comments are a way to help understand those tough blocks, but the real power of comments and where they shine is communicating business concepts. After all, it’s our job to help the business move forward, so that is where we have to focus our understanding.
I had a college professor who loved to kill us with documentation - his favorite example was How zero’s do you see? 000000000 and then he showed us 000|000|000
The professor said: See - I added more stuff and it’s more readable!
Years later - I realized you could use whitespace and change it this to get the same result: 000 000 000
Yep, must agree with the majority of posters here and disagree with Jeff. I start with comments as I set the architecture in place and then flesh it out with code. Yes, the comments typically stay in some form. And if you wanted your function (which I wouldn’t make something a function just to avoid a comment block), then it would require more work (which I would argue it needed anyway)…
I would have to agree that self-commenting variable names and function names area always more valuable.
As far as the other comments, my commenting style is constantly changing. Sometimes more, sometimes less. I nearly always think what I am currently doing is the best. I am sorry to say, but I think there are pluses and minuses to both. Assets and liabilities.
It’s actually just a preference. Seriously (as long as your code is actually easy to read).
Most of my work is cleaning up and maintaining existing code. Usually the original developer was a newbie, the code is hard to read and comments would make my life a lot easier. However, if the code was written by someone who knew what they were doing it’s usually obvious what is going on and comments are already in places where it makes sense to have a comment. I think the longer a developer codes, the more he/she learns to write self-documenting code and when/where to add a comment.
Junior developers rely on comments to tell the story when they should be relying on the code to tell the story.
I disagree. Comments are the context which code itself might not provide. Normal human reasoning does not always align with code architecture; this is why we consider a meaningful understanding of design patterns to be one sign of maturity (i.e., they take effort to internalize). Just as a graphical interface needs both a usable design and helpful documentation, so does code. This is because none of us are savant designers, capable of providing fully-comprehensible designs (to all audiences, locales, and experience levels!).
That’s my big picture response.
On the pragmatic side, engineers in any rapidly-changing field will need to frequently migrate between languages, platforms, and goals. While we should all have a firm grasp of programming fundamentals, the reality is that we often need to modify code we’re not seasoned veterans of.
If you have the luxury (or curse?) to work in one language for your entire career, then comments may seem superfluous. But throw in either a complex architectural solution (e.g., for performance or enterprise integration purposes), or new languages and libraries, and all-of-a-sudden a few comments here and there significantly improve task completion times.
Everyone benefits from comments – junior and senior engineers alike.
While comments are neither inherently good or bad, they are frequently used as a crutch. You should always write your code as if comments didn’t exist. This forces you to write your code in the simplest, plainest, most self-documenting way you can humanly come up with.
Disagree. Comments exist for a reason, we should make use of them, not write code that doesn’t need comments. Its not like comments are included in the compiled code. Shit most editors, make comments a different colour, you can easily ignore them. You know your blogs bug me. You moan about everything, php, xml are ones that stick out in my memory. Maybe you are an old school programmer who doesn’t like the new breed. But i’m afraid we are in a field where what’s new is old before it hits the mainstream. You need to adapt man!
Back to your comments hissyfit, I try to write efficient code ie use less memory, less cpu time etc… This some times leads to the code being hard to understand, no matter who is looking at it. Yea i try to keep it simple and plain, but sometimes to get that speed plain and simple doesn’t work. So comments come in, not on every line, hell no, but a little summary saying what the method does is quite fine.
As stated above by several others, my most common use of comments is for business logic. As the majority of applications I work on are complex applications with obscure business rules, leaving comments definitely helps future developers on the project.
// Uses Newton Raphson
private double SquareRootApproximation(n)
is pretty weak. I’d rather see a comment here than the first one. While I think you do have a good point about bad comments, please try to find a better example before you make your point. The current example is terrible because it does need at least one comment to be completely readable and easy to maintain and therefore, weakens your point considerably.
At school, the only thing the profs teach in the first 8 weeks is commenting. In my first year the teacher would knock points off every program we wrote, if there wasn’t at least one comment for every line of code.
Scott please bring some perspective to you blog entries, you make some valid points but why do you see the need to make everything so extreme?
I promise to carry on reading but I would prefer a more balanced discussion. I appreciate this is YOUR blog, but as you have clearly positioned yourself as a semiprofessional blogger, I’m not sure it is becoming of you to be so myopic.
I think the one point developers should take out of this is the bolded note You should always write your code as if comments didn’t exist. It’s probably one of the hardest tasks in our world and for those of you against self-describing, simple code, shame on you. There is enough complexity in the systems we produce that it makes little sense to have it at the functional level.
I am often guilty of poorly name variables (love the 1-, 2-, and 3-letter names…) but I often find myself going back and renaming them later. My past excuses for short names has since been trumped by Intellisense – less time is compromised by typing long names as the IDE does it for me now.
I’ve had one what-the-heck moment with some critiqued code. The first was with a continue statement in C++. You should put a comment in there to say what ‘continue’ does. My confused reply – You want me to explain a keyword of the language?
The last comment as I’m typing this is In a perfect world our comments would write the code. I like the implications of it – imagine a world where people used proper grammar and spelled words correctly…
A slight side-note:
If the best code is no code, what is the best comment?
lets think about the ‘best code is no code’ theory…
Does moving your logic into a config file really make ‘less code’?
What if your config file is really ‘perl’ expressions that get 'eval’d?
Alternately, what if the only way to record how some ‘non-coding’ configuration is through some umpteen series of screenshots for what buttons you clicked?
Sometimes the best code is code.
Could you write something about that?
Please?
Pretty Please?
Histo-doc: Ever-increasing comment section detailing revision history, typically duplicating information in Revision Control.
Igno-doc: Comment revealing author’s lack-of-understanding of necessary algorithms, alternate syntax, etc.
Personally, I believe in minimal commenting in-code (doesn’t count Javadoc documentation, which I don’t consider comments) only to warn subsequent visitors (like me during maintenance) about certain code sections that are arranged a certain atypical way on purpose, i.e. to workaround something somewhere else. I prefix these with IST for Important Safety Tip! This heads off the What the F*** was he doing here? impulse to just rip it out and re-do it the right way.
