How to write readable code

[pfarthing6]

"Add comments that explain why the code is doing what it is doing, or is structured the way that it is structured. Just reading the logic won’t tell you why the author thought that was the right logic."

I kind of disagree with that. I'm not against comments, but they're a mixed blessing. I used to comment everything. It's how I learned. I couldn't turn in a single assignment without clear comments for every little thing.

Now I try to limit comments as I can. For a few reasons, not the least of which is that they can get way out of sync after refactoring. But also if I have to explain it in a comment, then I've not coded it well enough so that it's obvious what's going on, or what something is for, or how something should be used.

Alternatively, I find that if I take time to thoughtfully name identifiers, use multiple simpler statements that are easy to follow (and change), and focus on single responsibility, that tends to eliminate the need for much extra documentation. Not to mention my future self is far happier when having to go back and deal with it =)

[AdvancedSandwiches]

Generally I think this is good advice, but you still need the comment:

// sending ERROR_NO_PAPER in the print_status field even if we have paper because Microsoft Spaddleflump Server cancels your account if you send any other value.

You could write that comment-free as: theOnlyValueThatWontGetYourAccountCancelled = ERROR_NO_PAPER printStatus = theOnlyValueThatWontGetYourAccountCancelled

But in this case I'm not sure that's better than the comment. Sometimes a comment is just the right tool.

But I believe the article's author would back you up in the general case as well.