Clean Code

The Sonar solution is designed to help you achieve a state of Clean Code, that is, code whose attributes make your software reliable, secure, and maintainable. 

Concepts

• Clean Code attribute: A characteristic that contributes to Clean Code. Attributes are grouped under four main categories: consistent, intentional, adaptable, and responsible. Code is considered Clean Code when it has these attributes.
• Software quality: A characteristic of software that contributes to its lasting value. There are three software qualities: security, reliability, and maintainability.
• Issue: A problem in your code that prevents it from being Clean Code. Each issue is linked to one Clean Code attribute which is associated with one or more software qualities, each with a level of severity.

Clean Code attributes

Issues detected by the Sonar Scanner are impacted by Clean Code attributes that define code health. The characteristics of these attributes contribute to the improvement of your code.

Attributes are classified/grouped into four main categories: consistent, intentional, adaptable, and responsible.

Consistent

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.

• Formatted: The code presentation is 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. The casing, word separators, suffixes, and prefixes used in the identifiers have purpose, without arbitrary differences.

Intentional

The code is precise and purposeful. Every instruction makes sense, is adequately formed, and clearly communicates its behavior.

Intentional code is clear, logical, complete, and efficient.

• 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, 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

The code is structured to be easy to evolve and develop 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.

• 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 checks that provide confidence in the functionality. It has enough test coverage which enables changes in implementation without the risk of functional regressions.

Responsible

The code takes into account its ethical obligations on data, as well as societal norms.

Responsible code is lawful, trustworthy, and respectful.

• 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 such as 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.

Software qualities

Clean Code leads to software that is secure, reliable, and maintainable. These three aspects are called software qualities in the Sonar solution, and they contribute to the long-term value of your software.

When an issue is detected in your code, it affects one or more of the three software qualities with a varying level of impact. The level of impact determines the severity of the issue which can be: high, medium, or low. 

Understanding issues in your IDE

An Issue is a problem in your code that prevents it from being Clean Code. Issues found in code are linked to Clean Code attributes, and these attributes signify how your code will impact one or more software qualities. Software qualities determine the overall severity of an issue that feeds back into the overall status of your code when implementing a Clean as You Code methodology; please see the SonarQube or SonarCloud documentation for more about Clean as You Code.

An issue’s Clean Code attribute, software qualities, and severity are presented to you when opening the Sonar Rule Help view. Below the rule title, you will find the Clean Code issue badges that highlight an issue’s Clean Code classification. 

Be sure to check out the Investigating issues page for more details about how issues appear in your IDE.