Add comments to explain ideas.

Some things are not obvious from self-documenting code.

Comments should explain why choices were made. They should talk about the history of the code and what led to the current approach. Comments should cover ideas not shown in the current source code. Source code by itself only reveals so much.

The variable and method names should make it obvious what the code is doing. We don’t need comments to explain what the code does. That is the code’s job. Comments should explain why the code does what it does.

This is much easier if a method does only one thing. If you see the word “and” in a method name, that’s a hint it may be doing too much.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: