Is it possible to write good and understandable code without any comments?

Question

Can any one suggest what is the best way to write good code that is understandable without a single line of comments?

Answer 1

Read Code Complete, 2nd Edition cover to cover. Perhaps twice.

To give some specifics:

• Making code readable
• Eliminating code repetition
• Doing design/architecture before you write code

Answer 2

Yes, you can write code that doesn't need comments to describe what it does, but that may not be enough.

Just because a function is very clear in explaining what it does, does not, by itself, tell you why it is doing what it does.

As in everything, moderation is a good idea. Write code that is explanatory, and write comments that explain why it is there or what assumptions are being made.

Answer 3

I believe it's possible, if you consider the fact that not everybody likes the same style. So in order to minimize comments, knowing your "readers" is the most important thing.

In "information systems" kind-of software, try using declarative sentence, try to approximate the code line to a line in english, and avoid "mathematical programming" (with the i,j and k for index, and the one-liners-to-do-a-lot) at all costs.

Answer 4

Use descriptive variable names and descriptive method names. Use whitespace.

Make your code read like normal conversation.

Contrast the use of Matchers in Junit:

assertThat(x, is(3));
assertThat(x, is(not(4)));
assertThat(responseString, either(containsString("color")).or(containsString("colour")));
assertThat(myList, hasItem("3"));

with the traditional style of assertEquals:

assertEquals(3, x);

When I look at the assertEquals statement, it is not clear which parameter is "expected" and which is "actual".

When I look at assertThat(x, is(3)) I can read that in English as "Assert that x is 3" which is very clear to me.

Another key to writing self-documenting code is to wrap any bit of logic that is not clear in a method call with a clear name.

if( (x < 3 || x > 17) && (y < 8 || y > 15) )

becomes

if( xAndYAreValid( x, y ) )  // or similar...

Answer 5

You usually can turn your comment into a function name something like:

if (starColourIsGreaterThanThreshold(){
    doSomething(); 
}

....

private boolean starColourIsGreaterThanThreshold() { 
    return starColour.red > THRESHOLD && 
           starColour.blue > THRESHOLD && 
           starColour.green > THRESHOLD
} 

Answer 6

I like to 'humanise' code, so instead of:

if (starColour.red > 200 && starColour.blue > 200 && starColour.green > 200){
   doSomething();
}

I'll do this:

bool starIsBright;
starIsBright = (starColour.red > 200 && starColour.blue > 200 && starColour.green > 200);

if(starIsBright){
   doSomething();
}