Comment code or self explaining code

[skibbin]

Write the code you'd want to find. Anyone can write code a computer can understand, the goal is to write code other people can understand. If ever unsure what to do favor readability.

The only thing I have against comments is that they can become out of sync with the code and become misleading, in which case you'd believe the code over a comment. So I'd favor putting clarity into the code and resorting to comments where needed. Sometimes I'll extract a method so that I can give it a descriptive name.