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.

I am asking this because I have seen places where, whoever coded initially had provided proper comments, but later on modifications were made to the code but the comments were left untouched. I remember reading somewhere " Don't get suckered in by the comments, debug only code".

So is it a good/ relevant/ practical idea that tells the scope of the comments so as to prompt the developer for editing the comment.

Your thoughts.

share|improve this question

migrated from stackoverflow.com Nov 24 '11 at 15:39

This question came from our site for professional and enthusiast programmers.

    
I don't know what you mean by "tells the scope" -- but that's wise advice you received in the past. (Someone here once apologized for all their comments being in Russian -- but it was wonderful -- because I couldn't read them, they couldn't lead me astray. When debugging, definitely ignore the comments.) –  sarnold Nov 23 '11 at 10:00
    
by scope i mean that the comments come with their own scope. That they are applicable only to the portion in the code. Having that would tell a developer that if any logic has changed in the sub routine then comments need to be adjusted too. –  Rig Veda Nov 23 '11 at 10:04
1  
Developers should revise comments whenever they change code. It should be innate behaviour. –  ThePower Nov 23 '11 at 10:05
    
If the code and the comments disagree, then probably both are wrong. –  Kaz Dragon Nov 23 '11 at 10:25
    
fyi, that quote is Dave Storer if I recall correctly –  CaffGeek Nov 24 '11 at 16:20

1 Answer 1

up vote 3 down vote accepted

Definitely. All comments have scope, whether implicit or explicit. As a general rule, it's helpful to your successors to be reasonably explicit about scope.

Vertical space is an inexpensive way to delineate scope.

I often try to convey scope when writing comments by either:

  1. inserting a linebreak or two before the comment, to keep it visually grouped with the block of code whose behavior it's intended to document
  2. or defining a logical block of code, and adding the comment at the top of that block.

In C, #1 would look like:

doStuff();
doOtherStuff();

// comment explaining the intent of the following three lines
int i;
for(i=0;i<10;++i)
    doMoreStuff(i);

doOtherStuff();

In C, #2 would look like:

doStuff();
doOtherStuff();

{
    // comment explaining the intent of the following three lines
    int i;
    for(i=0;i<10;++i)
        doMoreStuff(i);
}

doOtherStuff();

In this second example, the extra curly brackets also help by minimizing the scope of variable i.

share|improve this answer
1  
Basically yes, but defining a new function with proper name is often better option: function then becomes THE comment and is checked by compiler (doesn't rot so quickly). –  MaR Nov 24 '11 at 15:56

Your Answer

 
discard

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