Clean Coding

It is essential to code cleanly in order to be understood by other programmers, and also to understand your own code.

Names

• Choose revealing names, even if they are long.
• Do not leave any false clues or possible double interpretations in the names.
• Write similar concepts in a similar way.
• Avoid clutter, such as "Data" or "Info".
• Choose searchable names (e.g. "MAX STUDENTS PER ROW").
• Use one letter names only for local variables.
• Do not code your names.
• Do not choose too clever names.
• Choose one word per concept.
• Choose names known to programmers.
• Use long names for long scopes, and vice versa.

Class names

• Choose nouns or noun phrases.
• Avoid verbs.

Method names

• Choose verbs or verb phrases.

Functions

• Keep it short.
• Avoid too deep levels of indentation.
• Do only one thing.
• Everything a function does should be at the same level of abstraction.
• Choose a descriptive name.
• Don't be afraid of long names.
• Avoid arguments if possible.
• Do not use flag arguments, but create two functions.
• If a function must have many arguments, consider creating objects.
• Avoid side effects: a function should not perform hidden actions that change the system.
• Avoid output arguments.

Exceptions

• Prefer exceptions to error codes.
• Extract try/catch blocks into their own functions.

Comments

• Do not compensate for bad code with comments.
• The best comment is the one you can avoid writing.
• Sometimes you have to write legal comments.
• Some comments can be informative.
• A comment can :
  • Explain a decision.
  • Clarify an unclear argument.
  • Warn of consequences.
  • Predict something to be done (TODO comment).
  • Amplify the importance of a point.
• Avoid redundant or misleading comments.
• Avoid forced comments (force yourself to provide a document).
• Avoid logging comments.
• Avoid comments that repeat the obvious.
• Avoid positional comments (a succession of ////// for example).
• Avoid putting code in comments.
• Do not give global information in a comment.
• Do not include too much information in a comment.
• Comments should be carefully crafted and written in the best possible way.

The Classes

• The details of the data should not be exposed, but should be exposed in abstract terms. In other words, no object should show its internal structure.
• Do not pass "null" to methods.
• Never return "null" to methods.
• They should contain private instance variables first, then public, then public functions.
• Classes must be small.
• The name of a class describes its responsibilities.
• A class must have only one reason to be modified.
• Each method of a class should manipulate as many attributes as possible (cohesion).
• Do not make a class dependent on its derived classes.
• Well-defined modules offer very small interfaces allowing to do a lot with little.

Code Formatting

• If working in a team, agree on a common formatting.
• The level of detail in the code should increase as you move down the module.
• Separate groups of ideas with blank lines.
• Related concepts should be close together.
• Variables should be placed as close as possible to their initialization.
• Instance variables are declared at the beginning of the class.
• Two functions calling each other must be close.
• Two related concepts must be close.
• Short lines must be written.
• Assignment operators are spaced out.
• Indent the code to make the hierarchy visible.

The Tests

• Whenever you write production code, you need code to test it.
• Test code is just as important as production code.
• Testing means you don't have to be afraid to change the code.
• One assertion per test.
• Tests should be fast.
• Tests should be independent.
• Tests should be reproducible in any environment.
• Tests should have a binary result, either passing or failing.
• Tests must be written just before the production code that allows them to pass.
• Test to boundary conditions.
• Do not ignore a test that does not work.

General

• Explain in the code, it must be very explicit.
• You should not have several different languages in the same source code.
• Think about behaviour at the limits.
• Neutralizing safeguards presents a risk.
• Eliminate redundancies.
• Do not be inconsistent in your code.
• Delete unnecessary or unused code.
• Responsibilities must be placed correctly.
• Use explanatory variables.
• Understand the algorithms you create.
• Prefer polymorphism to conditions and switches.
• Replace magic numbers by named constants.
• Encapsulate conditional expressions.
• Do not be arbitrary, the structure of the code must be justified.
• Functions should be down to one level of abstraction.
• Avoid transitive navigation: a module should only know the modules it collaborates with.

Design Principles

• Identify the aspects of your application that vary and separate them from what stays the same
• Program to an interface, not an implementation
• Favor composition over inheritance
• Strive for loosely coupled designs between objects that interact
• Classes should be open for extension, but closed for modification
• No variable should hold a reference to a concrete class. No class should derive from a concrete class. No method should override an implemented method of any of its base classes.
• Solve things the simplest way possible

These are just principles, and it's not mandatory to follow them. Sometimes it's better not to do!

META

Status:: #wiki/notes/germinating
Plantations:: Programming
References:: Clean Code