Clean Code: a Handbook of Agile Software Craftmanship

Zainal Hasan |

Your code is clean if it can be easily understood by everyone in your team. Clean code can be read and enhanced by another developer other than you. Let's start how to do write clean code!

General Rule

  • Follow the standard convention for your language or your framework
  • Keep it simple stupid. Simpler is always better. Reduce complexity as much as possible
  • Boy scout rule. Leave the campground cleaner than you found it
  • Always find the root cause

Code Smells

  • Rigidity. The software is difficult to change. A small change causes a cascade of subsequent changes
  • Fragility. The software breaks in many places due to a single change
  • Immobility. You cannot reuse parts of the code in other projects because of involved risks and high effort
  • Opacity. The code is hard to understand
  • Needless Complexity
  • Needless Repetition

Design

  • Keep configurable data at high levels
  • Prefer polymorphism to if/else or switch/case
  • Separate multi-threading code
  • Prevent over configure-ability
  • Use dependency injection
  • Follow the Law of Demeter. A class should know only its direct dependencies

Object and Data Structures

  • Hide internal structure
  • Prefer data structures
  • Avoid hybrids structures (half object and half data)
  • It should be small
  • Do one thing
  • A small number of instance variables
  • The base class should know nothing about their derivatives
  • Better to have many functions than to pass some code into a function to select a behavior
  • Prefer non-static methods to static methods

Functions

  • Small
  • Do one thing
  • Use descriptive names
  • Prefer fewer arguments
  • Have no side effects
  • Don't use flag arguments. Split method into several independent ones

Comments

  • Don't be redundant
  • Don't add obvious noise
  • Don't use closing brace comments
  • Don't comment out code. Just remove it
  • Always try to explain yourself with code
  • Use as an explanation of intent
  • Use as clarification of code
  • Use as a warning of consequences

Structure

  • Keep lines short
  • Don't break indentation
  • Separate concepts vertically
  • Don't use horizontal alignment
  • Related code should appear vertically dense.
  • Declare variables close to their usage.
  • Place functions in the downward direction
  • Similar functions should be close
  • Use white space to associate related things and disassociate weakly related things

Understandability

  • Be consistent
  • Put the processing for boundary conditions in one place
  • Use explanatory variables.
  • Avoid negative conditionals
  • Don't write methods that only work correctly depending on the external state.
  • Prefer dedicated value objects to primitive types

Naming Convention

  • Choose descriptive and unambiguous names
  • Make a meaningful distinction
  • Use pronounceable names
  • Use searchable names
  • Replace magic numbers with named constants
  • Avoid encodings
  • Don't append prefixes or type information

Tests

  • One assert per test
  • Readable
  • Fast
  • Independent
  • Repeatable

Reference

Related post