Welcome to the first post for a hypocrites guide to comments!

My first piece of advice in my guide to comments is that you shouldn’t use comments.

That is, if you choose your variable names and method names well, lay out your code well and your code is doing something trivial ( I mean really trivial, not something that seems trivial now but won’t be in three months time when you’re no longer immersed in the project) then your code might not need comments.

To illustrate this consider have a look at this code:

float a(List <int> b)
 int c = 0; float d = 0;
 for (int i = 0; i < b.Count; i++){
 if (b[i] != 0)
 d += b[i];
 return d / c;}

Can you work out what that code does? How long did it take you to work it out?

Now look at this code:

float getAverageNonZeroMark(List <int> pListOfMarks)
   int numberOfNonZeroMarks = 0;
   float totalSumOfNonZeroMarks = 0;
   for (int i = 0; i < pListOfMarks.Count; i++)
      if (pListOfMarks[i] != 0)
         totalSumOfNonZeroMarks += pListOfMarks[i];
   return totalSumOfNonZeroMarks / numberOfNonZeroMarks;

Can you work out what that code does?

From the machine’s perspective these two pieces of code are pretty much the same. I expect that the compiler will perform the same optimizations on both pieces of code and two end results may well be identical. From a programmers perspective though, the two pieces of code are far from equal.