Clean Code is ultimately about maintainability, readability and productivity of your code. It should do exactly what you think it does and should be fairly simple to reason about. It should contain minimal, if not non-existent, code duplication, it should have tests that assert every single nook and cranny of your code (within reason but still aim to go as far as you can). Functions, variables, classes, tests, procedures, subroutines are accurately named. Clean code is precise. Clean code makes it clear that your code does one thing and one thing well. Clean code is well intentioned and appears to be written by someone who cares.
Tenets
Naming
- Names should be intention revealing. Care should be taken to ensure that the intention of the code being written is very clear. If a name requires a comment it is not revealing enough or needs to be broken up into smaller pieces.
- Avoid unnecessary encodings that would require extra mental effort to reason about
- Avoid names that disinform the reader as to what the code does.
accountList
is a bad name for a variable that is not a list. Avoid using names are extremely similar to each other (newAccountFromDatabase
, newAccountFromOldDatabase
) as they can disinform the reader.
- Ensure adequate context is added to names. Think of how the name will be called and read and attempt to ensure there is enough context surrounding the name chosen. At the same time avoid Gratuitous context such as added unnecessary encoding. The goal should be to add only very necessary context. Think, can I make this more concise?
- Use searchable names. This makes finding variables easier
- The names of variable should match the scope. Names that will be passed around and used more often are best when longer. Names that will only span a few lines can be short e.g. for loop variables. Ultimately try to make names as short as they can reasonably can be while aiming for clarity
- Do not use cute puns. The naming should be clear and precise. No need for extra reasoning about. Not everyone shares your
- Use solution domain names when possible. It is most likely that another technical stakeholder would be reading your code hence do not hesitate to use names of popular design patterns and solutions that would describe your code accurately to the technical stakeholder
- Use problem domain names as well when possible. If the system you are building has specific names for specific objects or methods, dont hesitate to include them if they contribute to the clarity of the code.
- Make clear distinctions.
accountList
, accountArray
, accountGroup
and accounts
could all mean the same thing hence multiple of these used in the same system does not make the distinction clear. Additionally naming variables with incrementing numerals at the end (account1
, account2
) gives poor clarity. Give more descriptive names to make clear what the distinction between the variables are.
- Use one word per concept. if you use
add
to denote adding an element to a group of other elements, ensure this is consistent across objects in your system. Later using insert
to denote this action can introduce some confusion and makes your code less clear
- Class names are best as nouns. Try to avoid introducing verb qualifiers in class names. Product is clearer than ProductManager. Object more succinct than ObjectData. Once again avoid gratuitous context.
- Class method names are best as verbs as they denote actions.
addUser
, deleteUser
, markCompleted
are good verb names to denote methods in classes.
Functions
- Functions should be short and do one thing clearly.
- Functions should operate at one level of abstraction. The content of a function should be one level below the name of the function. This helps keep them short. A good rule of thumb is to shorten the function until it is clear that its contents are at one level of abstraction and the name is not just a restatement of the code. If a function does only those steps that are one level below the stated name of the function, then the function is doing one thing