Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Commenting in code I believe is very important but recently I've been reviewing code that has left me wondering particular this one.

 //due to lack of confidence with web programming leaving this note in for now

What is the right level of granularity for code commenting?

EDIT: Obviously the above comment is shocking hence why I'm asking the question. I've recently noticed the inline comments in the code at my work place annoying. Instead of getting angry I want discovery the acceptable level of granularity for code commenting in the community.

share|improve this question
1  
is that a real comment?... it doesn't actually explain anything. That would be where I set the bar: They have to explain something, the reason for doing it, or the method used. –  Fosco Jun 22 '11 at 1:30
    
Yes this is a real comment from a very large complex system which handles hundreds-of-thousands of online trades to the stock exchange. Frustrated with this crap, I've turned to the programingstackexchange community, to see their experience and expectation regarding comments, hence the question. –  Nickz Jun 22 '11 at 2:07
2  
My suspicion is that this comment represents a very deep level of frustration. If you are are finding a lot of these, I would consider that a Red Flag ... about the organization. –  Peter Rowell Jun 22 '11 at 2:31
2  
@Nick: I understand that and laud your ambition -- I am absolutely in favor of good comments. I am "commenting on the comment" from the perspective of 38 years in the business. I have worked for some truly great companies and, unfortunately, a couple of complete losers, and I see comments in "legacy code" as being like hieroglyphs on the wall of a tomb: they tell a tale that should not lightly be ignored. Maybe things have changed since then, but maybe not. –  Peter Rowell Jun 22 '11 at 4:53
1  
@Nick: 8 years is a goodly amount of time. At about 8.5 years I went to work for myself, first with my own software company, and now as an independent consultant. OT: my favorite comment was one inserted by my friend and employee, Scott Southard, in the middle of some really gnarly code. He was describing a possible race condition when suddenly there was this ... "Spank me, whip me, make me write bad checks." Coffee literally came out of my nose. –  Peter Rowell Jun 23 '11 at 2:02

5 Answers 5

up vote 7 down vote accepted

The comment must be helpful. If it does not explain anything about the source code, it must be removed. It includes comments which repeat what the code does:

// Adding three to the variable n.
this.n = this.n + 3;

or some "false comments" which are in the wrong place:

// 2011-06-22 by Joe: replaced the SQL query by the new one.

Now, how often do we need to put comments? Is it one comment for each ten lines of code? One comment for every forty lines? Well, it depends. Complicated code may have lots of comments. For example it is the case when it is required to write a piece of code optimized for performance more than for readability. Easy to understand code on the other hand may do not have any comment at all (with a few exceptions, like the comments for every method or property or field).

So is //due to lack of confidence with web programming leaving this note in for now comment useful?

Well, it would be if it were more detailed. Reading this comment, we may think that the following code may not match the best practices, or not be very correct, or may even do something different from it was expected to do, unless in some circumstances. But we don't know anything precisely, so we must explore the code to guess (while comments are intended also to avoid forcing the reader to explore the code).

It would be helpful on the other hand to write comments like:

// I'm pretty sure that in web programming, we must keep the following data in
// sessions or in database, but writing specific database queries would be long,
// and I can't find how to use sessions, so I'll keep it this way.

or:

// I'm unsure that the JSON serialization must be done like this. Probably there
// is a method in .NET Framework to do it in one line, but I can't find it.
// TODO: search MSDN for a correct way to serialize to JSON in .NET.

I always suggest adding a TODO in those cases. When you write code, you are expected to know how to write it the correct way. But you may not have time to learn everything you need before writing it. By adding a TODO:

  • You notify the reader that you just postponed the search, but are willing to learn new things,
  • You can easily find TODO comments later (Visual Studio even shows you a list of TODO automatically from the comments),
  • You highlight that the code is not perfect, and must be modified before RTM.
share|improve this answer
    
+1 cheers, thanks for the feedback :) –  Nickz Jun 22 '11 at 2:05

The best commenting approach is to write clear simple code that is extremely obvious in its function and approach and does not need any comments at all.

Personally, I find in-line comments often detract from the ease of understanding a section of code because it breaks up the program logic and adds distractions. For that reason comments should only be used when the program logic itself isn't self-explanatory and you have to add them in order to make the program easier to understand.

share|improve this answer

I hate those kind of comments, for a few different reasons.

  • The code is never going to be as cheap or easy to implement "the right way" as it is right now.
  • If external factors are necessitating a sub par solution, that is intended to be fixed later, that should be documented in the bug tracker and, if customer affecting, in the release notes. Not in source code that no one has a compelling reason to revisit.
  • If it seems too trivial to track in a bug tracker, it's not worth noting. Either fix it before you check it in or let it go.
  • If you don't have confidence in your solution, or flat out don't know how to do it right, go ask. Hoping for someone smarter to happen across that code is not a feasible quality assurance technique.
  • If your solution is superior, but for a non-obvious reason, that's the kind of thing to document in the source.
share|improve this answer
1  
+1 for noting these things in the bug tracker. Although I often leave TODO comments for my own reference, I never rely on other people noticing them, and always fix out all the TODO comments before I consider the code finished and production ready. –  jhocking Jun 22 '11 at 3:09

Good code say how things are done.

Good comments say why the code is as it is.

Comments which doesn't say anything about why (or how if the code doesn't - but then the code should be refactored to say so), should be discarded. The one you show is most likely one of these.

share|improve this answer
1  
Plus one. How has this have little ups? –  MattyD Jun 22 '11 at 2:57

I wouldn't have worded it like that but I always comment a section I am unsure about. I often use a few asterisks to make it more visible too, so that I'll notice it while scanning over the code later.

In general, I put a comment at the beginning of every function to describe what that function does, what the parameters are, and what it returns. Then if it's a longish function I'll put comments within the function for every chunk of related code, usually around 5 or so lines. For example, if I have an if/else then I'll usually comment what's going on with each branch.

share|improve this answer
1  
+1: There is nothing wrong with a comment that warns about potential issues with the following code. However, the comment should give some explanation as to WHY the code might not be the best. –  unholysampler Jun 22 '11 at 1:52
4  
Comments in a longish function should be replaced by shorter functions, where the names replace the comments. Or the other way round: Make function names out of your comments. Use function names to describe, what the function does, and parameter names to describe, what the parameter does/is used for. –  user unknown Jun 22 '11 at 2:14
3  
While I generally refactor long functions into a bunch of short ones, personally I feel that being too slavish about that is counter-productive. For example, if the branches of the conditional are nudging a UI widget into different locations, then splitting those into separate functions would be pretty klunky. –  jhocking Jun 22 '11 at 2:34

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.