Clean code principles and best practices

In order to deliver software that is of high quality, reliable, maintainable, and secure, it is imperative that the underlying code is robust. By following best coding practices, organizations can achieve the agility, velocity, and scale of development needed for their business goals.

Consistent code

The code is written in a uniform and conventional way. All the code looks similar and follows a regular pattern, even with multiple contributors at different times. Consistent code is formatted, conventional, and identifiable. For example, when code is formatted well, it is systematic and regular, which reduces differences between authors’ coding styles and makes code much easier to review by peers on pull requests.

Formatted: The code presentation is well-organized, systematic, and regular. Non-semantic choices, such as spacing, indentation, and character placement, remain consistent throughout the codebase, maintaining uniformity across files and authors.

Conventional: The code performs tasks with expected instructions. Faced with equally good options, the code adheres to a single choice across all instances, preferring language conventions. This includes using the appropriate programming interfaces and language features.

Identifiable: The names follow a regular structure based on language conventions without arbitrary differences. The casing, word separators, suffixes and prefixes used in the identifiers have purpose, without arbitrary differences.

Intentional code

The code is clear, precise, and purposeful. Intentional code reads like it is written with attention and care to convey its purpose. Every instruction makes sense, is adequately formed, and simply communicates its behavior. Intentional code is clear, logical, complete, and efficient. For example, clear code is self-explanatory and transparently communicates its functionality, making it easier to understand the program and reducing the likelihood of bugs being introduced.

Clear: The code is self-explanatory, transparently communicating its functionality. It is written in a straightforward way that minimizes ambiguity, avoiding unnecessary clever or intricate solutions.

Logical: The code has well-formed and sound instructions that work together. It is free of explicit errors, contradictions, and commands that could be unpredictable or objectionable.

Complete: The code constructs are comprehensive and used adequately and thoroughly. The code is functional and achieves its implied goals. There are no obviously incomplete or lacking solutions.

Efficient: The code utilizes resources without needless waste. It prioritizes economical options when available, avoiding unnecessary consumption of memory, processor, disk, or network resources.

Adaptable code

The code is structured to evolve easily and with confidence. It makes extending or repurposing its parts easy and promotes localized changes without undesirable side effects. Adaptable code is focused, distinct, modular, and tested. For example, when code is modular it is organized and distributed to emphasize the separation between its parts, making it easier to manage and clearly define the relationships within.

Focused: The code has a single, narrow, and specific scope. Each unit should have only one concise purpose, without an overwhelming accumulation of instructions or excessive amounts of complexity.

Distinct: The code procedures and data are unique and distinctive, without undue duplication. The codebase has no significant repetition where it could be decomposed into smaller shared segments.

Modular: The code has been organized and distributed to emphasize the separation between its parts. The relationships within the code are carefully managed, ensuring they are minimal and clearly defined.

Tested: The code has automated quality tests that provide confidence in the functionality. It has enough test coverage which enables changes in implementation without the risk of functional regressions.

Responsible code

The code takes into account its ethical obligations on data and the potential impact of societal norms. Responsible code is lawful, trustworthy, and respectful. For example, when we classify code as lawful, we refer to it as code that respects licensing and copyright regulation, enabling a creator to license their own code and respecting others' licensing rights. Equally as important, code should be trustworthy and should not contain secrets.

Lawful: The code respects licensing and copyright regulation. It exercises the creator’s rights and honors other’s rights to license their own code.

Trustworthy: The code abstains from revealing or hard-coding private information. It preserves sensitive private information, like credentials and personally identifying information.

Respectful: The code refrains from using discriminatory and offensive language. It chooses to prioritize inclusive terminology whenever an alternative exists that conveys the same meaning.

Inspired by: https://www.sonarsource.com/solutions/clean-code/