Clean Code

Overview

Principles

• Elegant: Pleasing to read with clear structure and logic
• Efficient: Doesn't waste resources, performs well, and avoids complexity
• Error-free: Minimizes bugs, handles errors gracefully
• Expressive: Clearly communicates intent using meaningful names and comments
• Extensible: Easily adaptable to changing requirements
• Modular: Composed of small, reusable units following the single responsibility principle

Principle	Definition	Application	Benefits	Use Cases
APO	Always Plan for Obsolescence	System Architecture Technology Selection	Encourages anticipating and planning for the eventual obsolescence of technology components, frameworks, or platforms Mitigates the risk of technology becoming outdated and reduces the effort required for future migrations or upgrades	Selecting technologies for long-term projects Designing architectures that can easily accommodate future changes Incorporating backward compatibility into system designs
BDUF	Big Design Up Front	Software Development Process	Advocates for creating a detailed design before starting implementation While it may provide a clear plan initially, it can lead to rigid architectures and hinder adaptability to changing requirements	Projects with well-defined requirements and stable specifications Where changes are unlikely or costly to implement
Boy Scout Rule	Leave the code cleaner than you found it	Codebase Maintenance Continuous Improvement	Encourages developers to continuously improve the quality of code by making small, incremental changes whenever they work with it Over time, this leads to a cleaner, more maintainable codebase Fosters a culture of continuous improvement within the development team	Refactoring code during bug fixes or feature development Performing code reviews Addressing technical debt Enhancing code readability
DRY	Don't Repeat Yourself	Codebase	Reduces code duplication Encourages maintainability Improves readability Minimizes errors by ensuring that a single piece of knowledge has a single, unambiguous representation in the system	Refactoring code to eliminate duplicate logic Creating reusable functions or modules Enforcing consistency across the codebase
GRASP	General Responsibility Assignment Software Patterns	Object-Oriented Design Class Responsibilities	Provides guidelines for assigning responsibilities to classes and objects Helping to create systems that are easier to understand, maintain, and evolve Focuses on assigning responsibilities based on information expert High Cohesion Low Coupling	Identifying class responsibilities Determining collaboration between objects Defining the overall structure of an object-oriented system
KISS	Keep It Simple, Stupid	Design Implementation	Encourages simplicity in design and implementation Makes it easier to understand, maintain, and extend Overly complex solutions are more prone to errors and difficult to modify or scale	Designing user interfaces Writing code Designing system architectures Choosing between different approaches to solve a problem
Law of Demeter	Principle of Least Knowledge	Object-Oriented Design Dependency Management	Encourages designing classes with limited knowledge of other classes Reducing coupling and promoting encapsulation Helps in creating more maintainable and flexible code by minimizing the impact of changes in one class on others	Accessing object properties or methods through a limited number of intermediary objects Avoiding long chains of method calls between objects
Occam's Razor	The simplest explanation is usually the correct one	Problem Solving Decision Making	Prefers simpler explanations or solutions over more complex ones when multiple options are available Helps in avoiding unnecessary assumptions or complexity, leading to more straightforward and efficient solutions	Analyzing data Troubleshooting issues Making design decisions Evaluating competing hypotheses
PIT	Prefer Isolated Tests	Software Testing	Encourages writing tests that focus on testing one unit of functionality in isolation from other parts of the system Helps in identifying and diagnosing issues more effectively Promotes test independence, making it easier to refactor code without breaking tests Supports parallel test execution for improved performance	Writing unit tests Mocking external dependencies Testing individual components or modules Ensuring test suites are self-contained and repeatable
Principle of Least Surprise	Design should minimize astonishment	User Interface Design API Design	Behavior of a system or interface should be predictable and intuitive to users or developers Reduces confusion, errors, and the need for extensive documentation Leads to a better user experience and increased productivity	Designing user interfaces Defining API contracts Naming conventions for variables and functions Designing error messages and prompts
SLAP	Single Level of Abstraction Principle	Code Design	Advocates for maintaining a consistent level of abstraction within functions or methods Improves code readability and comprehension by ensuring that each function does one thing at a single level of abstraction Reduces cognitive overload by preventing mixing of high-level and low-level operations within the same function Facilitates easier debugging, testing, and maintenance	Breaking down complex functions into smaller, more focused functions Ensuring that each function performs a single task at a consistent level of abstraction
SOLID	Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion	Object-Oriented Design Code Modularity	Promotes maintainability, extensibility, and testability by emphasizing principles for designing well-structured, modular code Each principle addresses a specific aspect of software design, contributing to overall code quality and flexibility	Designing classes and interfaces Defining software architecture Refactoring existing code to improve its design
YAGNI	You Ain't Gonna Need It	Feature Development, Architecture	Prevents over-engineering by discouraging developers from adding functionality or architecture that is not immediately necessary. This avoids wasted effort and keeps the focus on delivering value to the customer	Avoiding premature optimization, deferring implementation of features until they are requested by users or required by business needs

Benefits

• Productivity: Simplifies writing, reading, debugging, testing, and maintenance, reducing time and effort for new features, bug fixes, and refactoring
• Quality: Enhances user experience and satisfaction by meeting both functional and non-functional software requirements such as performance, security, reliability, and usability
• Collaboration: Facilitates teamwork and knowledge sharing, enabling quick understanding of code and effective collaboration on complex projects
• Learning: Aids developers in skill improvement and technology acquisition through exposure to best practices, design patterns, and coding standards, enhancing coding abilities

Guidelines

General

• Follow standard conventions
• Keep it simple stupid
• Follow the Boy Scout Rule
• Always identify the root cause

Design

• Keep configurable data at high levels
• Favor polymorphism over if/else or switch/case statements
• Separate multi-threading code
• Avoid over-configurability
• Use dependency injection
• Adhere to the Law of Demeter

Understandability

• Be consistent
• Use explanatory variables
• Encapsulate boundary conditions
• Favor dedicated value objects over primitive types
• Avoid logical dependencies
• Avoid negative conditionals

Naming Conventions

• Opt for descriptive and unambiguous names
• Make meaningful distinctions
• Use pronounceable names
• Use searchable names
• Replace magic numbers with named constants
• Don't append prefixes or type information

Function

• Keep functions small
• Ensure functions do one thing only
• Use descriptive names
• Favor fewer arguments
• Functions should not have side effects
• Avoid flag arguments

Comments

• Strive to explain yourself in code, not comments
• Avoid redundancy in comments
• Don't add unnecessary noise through comments
• Don't use closing brace comments
• Don't comment out code, just remove it
• Use comments to explain intent, clarify code, and warn of consequences

Source Code Structure

• Separate concepts vertically
• Related code should appear vertically dense
• Declare variables close to where they are used
• Dependent functions should be close together in your code structure
• Similar functions should be grouped together in your code structure
• Place functions in a downward direction in your code structure
• Keep lines of code short for readability purposes
• Avoid horizontal alignment in your code structure
• Use white space to associate related things and disassociate weakly related things in your code structure
• Maintain consistent indentation throughout your code structure

Objects and Data Structures

• Internal structure should be hidden within objects and data structures
• Favor data structures over objects when possible
• Avoid hybrid structures (half object and half data)
• Objects and data structures should be small and do one thing only
• They should have a small number of instance variables
• Base classes should not know anything about their derivatives
• It's better to have many functions than to pass some code into a function to select a behavior
• Non-static methods are generally preferable to static methods

Testing

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

Code Smells

• Rigidity
• Fragility
• Immobility
• Needless Complexity
• Needless Repetition
• Clearness