On code commenting

You would have heard often about ‘Commenting your code is crucial’.

I used to have a bunch of comments above each function I write like

/*
 * This does something blah blah
 */
private void func() {
} 

And for clarifying the code I used to have comments by the side at critical points

for (String item: Names) {   // Find all Names that has something
}

The issue with the above is that the comment is on the side along with the code making it difficult to read that line.

Better way instead is to have comments that describe your code as

// FIND ALL THE NAMES THAT HAS SOME BLAH BLAH
for (String item: Names) {
}

In the above commenting style, the comment is very clear in upper case describing the code below. The upper case helps to differentiate it from the code in lower case. So no cognitive overhead. Since it is not on the same line as the code, you can describe the code much better without the comment crossing the field of view.

So when you describe your entire function body with such comments, it is possible to easily read only the comments and get what the function is doing, without bothering about the code.

We can apply the same technique to the top level comment as well.

/*
 * THIS DOES SOMETHING BLAH BLAH
 */
private void func() {
}

However, there can be situations where you are say describing some variables as to what they are

int x = 0;    // Blah Blah
int y = 0;        // Blah Blah

Since the space occupied by the code is very less and also most of these are just single line declarations, we can maintain a normal lower case comment by the side to tell what they are. Upper case can be used if there are not too many comments to be made one after another.