Comments on comments...

[tonyyeb]

Hi all

I develop mainly in ASP, Javascript and HTML. I use comments to give a general idea of what is going with detail only about the most complicated or obscure processes.

What method of commenting do other people use? Do you force yourself to comment every little detail or do you say ensure a comment for every x number of lines? Or do you not even bother?!

 

[fez]

I would recommend reading some books on the subject such as 'coders at work'. The idea is that your code should be written and organided in such a way that it speaks for itself. Method names etc should reflect exactly what they do.

If you look at well written code it does almost talk to you and tell you what its doing. Then you can just use comments as a tool to fill in some tricky bits.

 

[Dj_Jestar]

Tests are the main form of documentation in our projects. Comments are used only when the code or test does not explain in simple enough terms what it is used for

An example of something we have just done, is when using MSMQ to peek and then receive messages

C#

public void PeekCompleted(object sender, PeekCompletedEventArgs e)
{
  lock (_lockObject)
  {
    try

    {
      var message = (Message)((MessageQueue)sender).EndPeek(e.AsyncResults);
      WebService.SendMessage((WebMessage)message.Body);
      ((MessageQueue)sender).Receive(); // message processed, remove message from queue
    }
    finally
    {
        ((MessageQueue)sender).BeginPeek(); // start peeking again.
    }
  }
}

 

[_TubbZ_]

I use Notepad++ at work all the time and the way i have setup the quick text features to input function stubs it also adds the relevant comments and comment headers so i fill it out as a force of habit. I have currently been given a HUGE chunk of uncommented undocumented code in an area where i have no idea whats going on so I really value sensible coding and commenting.

But then the people who half coded what i am doing before me had been doing the same things for 10 years so its second nature to them i guess.

 

[NathanE]

We use XML documentation comments on all publicly exposed members. Sometimes even for private stuff that isn't entirely obvious.

Then we use standard // comments near code to explain WHY it is doing something, not WHAT.

You can always tell good comments from bad comments because when you read them a year or two later you either think "what a pointless comment, I already knew that, it was obvious" or "that was helpful and it saved me more time than it took to read".

There is a lot of noise on the web that comments shouldn't be needed. That your code should be so clean and perfect that its intent is always perfectly clear. But in the real world they are still needed. At least in my opinion.