Clean Code with Uncle Bob

In this article, I shared the notes I took in the Meaningful Names, Functions, Comments and Formatting chapters while reading the Clean Code Book.

Names are everywhere in software.

The Rules of Meaningful Names:

• Use descriptive names
• Make meaningful distinctions
• Use pronounceable names
• Use searchable names
  • Single-letter names can ONLY be used as local variables inside short methods.
• Avoid encodings
  • It is an unnecessary mental burden when trying to solve a problem.

Functions are the first line of organization in any program.

The Rules of Functions:

• Small

  • The first rule: They should be small

  • The second rule: They should be smaller than that.

• Do one thing

  It should be very clear.

• Use descriptive names

  • A long descriptive name is better than a short enigmatic name.
  • A long descriptive name is better than a long descriptive comment.

• Choose fewer arguments

  The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification—and then shouldn’t be used anyway.

• Don't use flag arguments

• Don’t repeat yourself

Nothing can be quite so helpful as a well-placed comment.

The Rules of Comments:

• Comments Do Not Make Up for Bad Code

  • One of the more common motivations for writing comments is bad code.

• Explain Yourself in Code

• Good Comments

  • The only truly good comment is the comment you found a way not to write.

• Legal Comments

  • Where possible, refer to a standard license or other external document rather than putting all the terms and conditions into the comment.

• Informative Comments

  • It is better to use the name of the function to convey the information where possible.

• Use as warning of consequences.

• TODO Comments

  • TODOs are jobs that the programmer thinks should be done, but for some reason can’t do at the moment.

  • Whatever else a TODO might be, it is not an excuse to leave bad code in the system.

• Mumbling

  • If you decide to write a comment, then spend the time necessary to make sure it is the best comment you can write.

• Don't comment out code. Just remove

• Don’t Use a Comment When You Can Use a Function or a Variable

• Don’t put interesting historical discussions or irrelevant descriptions of details into your comments

You should take care that your code is nicely formatted

Code formatting is about communication, and communication is the professional developer’s first order of business.

The Rules of Formatting:

• The Newspaper Metaphor

  • We would like a source file to be like a newspaper article. The name should be simple but explanatory.

  • The topmost parts of the source file should provide the high-level concepts and algorithms. Detail should increase as we move downward, until at the end we find the lowest level functions and details in the source file.

• Vertical Openness Between Concepts

  • Each line represents an expression or a clause, and each group of lines represents a complete thought. Those thoughts should be separated from each other with blank lines.

• Related code should appear vertically dense.

• Conceptual Affinity

  • Certain bits of code want to be near other bits. They have a certain conceptual affinity. The stronger that affinity, the less vertical distance there should be between them.

• Don't break indentation.

• Team Rules

  • A team of developers should agree upon a single formatting style, and then every member of that team should use that style. We want the software to have a consistent style.

I will add other chapters as I read them.

Thanks for reading.