Now I’m sure we’ve all heard this once or twice before:

Add comments to your code, as often as you can.

Unfortunately this innocent **good advice is bad in practice**. Well not bad as in inapplicable, but rather people seem to be a little clueless to how to actually apply it to practice.

Let us start with this mess:

package com.wordpress.sixmoon;

public class txNrm {

public static double proc (double[] in) {

double re = 0;

for (int i = 0; i < in.length; i++) {
re += Math.abs(in[i]);
}
return re;
}
public static double proc (double[][] in) {
double re = proc(input[0]);
double c;
for (int i = 1; i < in.length; i++) {
c = proc(in[i]);
if (re < c) re = c;
}
return re;
}
}[/sourcecode]

First of all, can this pile of junk get better if we add comments to it? The answer is, no. Computer code, for the most part, is designed to be to a certain point human readable. Do not fall under the illusion that adding more to unreadable code is going to make it more readable.

### The wrong way, on the right street

Nevertheless some people try, often beginners and often a lot like this:

package com.wordpress.sixmoon;

public class txNrm {

/** method that accepts as input a vector */

public static double proc (double[] in) {

double re = 0; // return

// loop though all values

for (int i = 0; i < in.length; i++) {
re += Math.abs(in[i]);
}
return re;
}
/** method that accepts as input a matrix */
public static double proc (double[][] in) {
double re = proc(input[0]); // initialize
double c; /* swap variable */
for (int i = 1; i < in.length; i++) {
c = proc(in[i]);
if (re < c) re = c; // new maximum
}
return re;
}
}[/sourcecode]

The simple lessons to learn, commenting is not what individual code snippets do, its what’s they are for (we can all see what they do). And, keep code clean to avoid having to write comments in the first place, or at all.

### The alternative way

The following example minimizes comments, to the essential bits. Often thinking of comments, as commenting to a blog, article etc gives out the best results.

Keep in mind that there is not fixed formula and depending on what you are working on will vary what your comments should be useful for (in the following mathematical context makes mathematical hints important).

package com.wordpress.sixmoon;

public class TaxicabNorm {

// Mathematical class for calculating “Taxicab norm”

// Norm is also known as “Manhattan norm”

public static double calculate (double[] A) {

double norm = 0.0;

for (int i = 0; i < A.length; i++) {
norm += Math.abs(A[i]);
}
return norm;
}
public static double calculate (double[][] A) {
double norm = norm(A[0]);
double cache;
for (int i = 1; i < A.length; i++) {
cache = norm(A[i]);
if (norm < cache) norm = cache;
}
return norm;
}
}[/sourcecode]

As the code above shows, placing good comments makes spotting (obvious) errors easier.

#### End note

Remember, *clear code speaks for itself*, keep comments to just that, (lit.) *comments*. And by the way, do keep them in nice paragraph like blocks, it makes them so much easier to read, and keeps code clean as well.

## Program, Comments

Posted by: 7kittens on: April 13, 2009

Now I’m sure we’ve all heard this once or twice before:

Unfortunately this innocent

good advice is bad in practice. Well not bad as in inapplicable, but rather people seem to be a little clueless to how to actually apply it to practice.Let us start with this mess:

package com.wordpress.sixmoon;

public class txNrm {

public static double proc (double[] in) {

double re = 0;

for (int i = 0; i < in.length; i++) { re += Math.abs(in[i]); } return re; } public static double proc (double[][] in) { double re = proc(input[0]); double c; for (int i = 1; i < in.length; i++) { c = proc(in[i]); if (re < c) re = c; } return re; } }[/sourcecode]

First of all, can this pile of junk get better if we add comments to it? The answer is, no. Computer code, for the most part, is designed to be to a certain point human readable. Do not fall under the illusion that adding more to unreadable code is going to make it more readable.

## The wrong way, on the right street

Nevertheless some people try, often beginners and often a lot like this:

package com.wordpress.sixmoon;

public class txNrm {

/** method that accepts as input a vector */

public static double proc (double[] in) {

double re = 0; // return

// loop though all values

for (int i = 0; i < in.length; i++) { re += Math.abs(in[i]); } return re; } /** method that accepts as input a matrix */ public static double proc (double[][] in) { double re = proc(input[0]); // initialize double c; /* swap variable */ for (int i = 1; i < in.length; i++) { c = proc(in[i]); if (re < c) re = c; // new maximum } return re; } }[/sourcecode]

The simple lessons to learn, commenting is not what individual code snippets do, its what’s they are for (we can all see what they do). And, keep code clean to avoid having to write comments in the first place, or at all.

## The alternative way

The following example minimizes comments, to the essential bits. Often thinking of comments, as commenting to a blog, article etc gives out the best results.

Keep in mind that there is not fixed formula and depending on what you are working on will vary what your comments should be useful for (in the following mathematical context makes mathematical hints important).

package com.wordpress.sixmoon;

public class TaxicabNorm {

// Mathematical class for calculating “Taxicab norm”

// Norm is also known as “Manhattan norm”

public static double calculate (double[] A) {

double norm = 0.0;

for (int i = 0; i < A.length; i++) { norm += Math.abs(A[i]); } return norm; } public static double calculate (double[][] A) { double norm = norm(A[0]); double cache; for (int i = 1; i < A.length; i++) { cache = norm(A[i]); if (norm < cache) norm = cache; } return norm; } }[/sourcecode]

As the code above shows, placing good comments makes spotting (obvious) errors easier.

## End note

Remember,

clear code speaks for itself, keep comments to just that, (lit.)comments. And by the way, do keep them in nice paragraph like blocks, it makes them so much easier to read, and keeps code clean as well.