Clean code — Does code smell? Part 2

In this article, we continue our exploration of code smells and how they indicate potential issues in our codebase. By understanding these code smells, we can identify areas of improvement in our code and apply techniques to refactor and improve its quality. Join us as we uncover the common code smells and learn best practices for writing clean and maintainable code. Please, before reading this article, we strongly recommend starting with Clean code — Does code smell? Part 1. A good reading and smell for your code!

Comments

The “Comments” code smell refers to the presence of excessive, misleading, or redundant comments in the code. While comments can be valuable for providing explanations or context, relying on them excessively to explain poorly written or complex code is considered a code smell. Clean code should be self-explanatory and readable, minimizing the need for comments.

Here are some reasons why overuse or misuse of comments can be considered a code smell:

Code Duplication:

• If comments are duplicating what the code already expresses, it can create confusion and the risk of inconsistency between the code and comments.

Maintainability:

• Comments that explain the obvious or provide redundant information can become outdated over time, leading to maintenance challenges.

Readability:

• The code should be clear and readable on its own. Excessive comments may clutter the code, making it harder to read and understand.

Misleading Comments:

• Comments that are outdated, inaccurate, or misleading can lead to confusion and incorrect assumptions about the code.

Lack of Refactoring:

• Relying heavily on comments might be an indication that the code itself requires improvement. It’s often better to refactor the code to be more self-explanatory.

To address the issue of excessive comments, consider the following strategies:

Self-Documenting Code:

• Write code in a self-explanatory way. Use meaningful variable and function names, follow a consistent coding style, and structure your code logically.

Remove Redundant Comments:

• Eliminate comments that merely repeat what the code is already expressing. Keep comments that provide valuable insights or context.

Refactor Code:

• If you find yourself needing to add comments to explain complex or confusing code, consider refactoring the code to make it more straightforward.

Use Comments Sparingly:

• Reserve comments for situations where additional context is genuinely needed, such as explaining complex algorithms, outlining design decisions, or providing information about external dependencies.

Regular Code Reviews:

• Conduct regular code reviews within your team to identify and discuss the use of comments. Ensure that comments add value and are accurate.

Here’s an example to illustrate the difference between well-written code and excessive comments:

Instead of the previous example, you can use your code to be the explanation, removing unnecessary comments. That comment probably in the future when someone else updates the function will be forgotten and explains a piece of wrong information about the code.

Comments should be reserved for strict cases where the code alone might not convey the necessary information. The previous function is clear, by reading the code we can understand the inputs, logic, and output. We know what’s expected as a result.

Nested Code Blocks

The “Nested Code Blocks” code smell refers to the situation where code contains excessive levels of nesting, typically within loops or conditional statements. Deeply nested code blocks can make the code harder to read, understand, and maintain. Excessive nesting can also indicate a need for refactoring to improve the structure and clarity of the code.

Here are some reasons why excessive nesting is considered a code smell:

Complexity:

• Deeply nested code increases the cognitive load on developers, making it more challenging to follow the logic and understand the flow of execution.

Readability:

• Code with excessive nesting is often less readable. It can lead to “arrow code” where developers have to follow indentation levels to understand the program’s flow. The famous “callback hell” or similar antipatterns can be also considered a bad practice.

Maintenance:

• Modifying or adding features to code with deep nesting can be error-prone. Developers may inadvertently introduce bugs or unintended side effects.

Testing:

• Writing comprehensive tests for deeply nested code can be challenging, as it requires covering various combinations of conditions.

Scoping Issues:

• Deep nesting can lead to scoping issues and make it harder to track the lifecycle of variables, potentially introducing bugs related to variable reuse or unintended side effects.

To address the issue of nested code blocks, consider the following strategies:

Limit Nesting Levels:

• Aim to limit the number of nested levels within your code. If you find yourself nesting deeply, consider breaking down the logic into smaller functions or methods.

Extract Functions:

• Identify logical units of functionality within nested blocks and extract them into separate functions. This not only reduces nesting but also improves code modularity and readability.

Early Returns:

• Use early returns or continue/break statements to exit from nested blocks when a certain condition is met. This can simplify the logic and reduce indentation levels.

Guard Clauses:

• Use guard clauses to handle special cases or edge conditions early in a method, avoiding the need for deep nesting. It is a HUGE friend to solve issues with nested blocks.

Refactoring:

• Regularly review and refactor your code to eliminate excessive nesting. Consider whether the nesting is necessary or if there are more readable alternatives.

Here’s a simple example of refactoring to reduce nesting:

Refactored version:

In this refactoring example, the nested code blocks have been reduced by using early returns and simplifying the conditions. The refactored version is more readable and maintains the same logic. Remember, simple is better than complex to find bugs quickly.

Inconsistent Naming

The “Inconsistent Naming” code smell refers to the use of inconsistent naming conventions for variables, functions, classes, or other identifiers within a codebase. Inconsistent naming can make the code more challenging to understand, leading to confusion among developers and potentially introducing bugs. Clean code emphasizes the importance of consistent and meaningful naming to enhance readability and maintainability.

Here are some reasons why inconsistent naming is considered a code smell:

Readability:

• Inconsistent naming conventions can make it difficult for developers to quickly understand the purpose and usage of variables or functions.

Maintainability:

• Code with inconsistent naming is more prone to errors during maintenance. Developers might inadvertently use the wrong name or misunderstand the intended functionality.

Collaboration Issues:

• Inconsistent naming can create confusion in collaborative development environments. Team members may have different interpretations of identifier names, leading to misunderstandings.

Code Review Challenges:

• Code reviews become more challenging when inconsistent naming conventions are present. Reviewers may need to address naming inconsistencies, slowing down the review process.

Documentation:

• Inconsistent naming can affect the quality of documentation. If identifiers don’t follow a consistent naming pattern, it becomes harder to create clear and standardized documentation.

To address the issue of inconsistent naming, consider the following strategies:

Follow Naming Conventions:

• Establish and adhere to a consistent naming convention throughout your codebase. This includes guidelines for naming variables, functions, classes, constants, and other identifiers.

Use Descriptive Names:

• Choose descriptive and meaningful names for variables and functions. Avoid cryptic abbreviations and use names that convey the purpose of the identifier.

Document Naming Conventions:

• Document and communicate the naming conventions used in your project. This helps ensure that all team members are aware of the established conventions.

Refactor Inconsistencies:

• Regularly review your codebase for inconsistent naming and refactor identifiers to align with the established conventions. Many modern integrated development environments (IDEs) provide tools for refactoring.

Automated Tools:

• Use linting tools or static code analyzers that can identify and highlight naming inconsistencies. These tools can be integrated into your development workflow to catch naming issues early.

Here’s a simple example of inconsistent naming and its refactoring:

What does the previous code do? It isn’t clear, and we need to read with strong attention 3 or 4 times to understand better what’s happening. It isn’t a clean and clear code. Let’s change some things! Explain the magic numbers, and change the variables for clear values.

Better now? I think yes! Not it’s clear what it’s happening.

Feature Envy

Feature Envy is a code smell that occurs when a method or function in one class excessively uses or manipulates the properties and methods of another class. In other words, the method is more interested in the data or behavior of another class than its own. This can lead to poor design, decreased maintainability, and reduced flexibility in the code.

Here are some indicators and reasons why Feature Envy is considered a code smell:

High Dependency:

• A method in one class is making heavy use of the properties or methods of another class. This creates a tight coupling between the two classes.

Low Cohesion:

• The method is performing operations that are conceptually the responsibility of another class. This can lead to classes with low cohesion, where the methods and properties are not well-aligned with the responsibilities of the class.

Violation of Encapsulation:

• Feature Envy often results in violations of encapsulation principles, as one class is accessing and manipulating the internal details of another class.

Maintenance Challenges:

• Code with Feature Envy is more difficult to maintain, as changes in the implementation of one class can have cascading effects on other classes that depend on it.

Reduced Reusability:

• The class experiencing Feature Envy is less reusable, as its methods are tightly coupled to the details of another class. It becomes challenging to use the class in different contexts without bringing along unnecessary dependencies.

To address the issue of Feature Envy, consider the following strategies:

Move Methods:

• If a method in one class is heavily using the properties or methods of another class, consider moving that method to the class where the data or behavior it uses resides. This promotes better encapsulation and alignment of responsibilities.

Introduce Delegation:

• Instead of directly accessing the properties or methods of another class, consider using delegation. Create methods in the calling class that delegate specific tasks to the other class, encapsulating the interactions.

Refactor for Better Design:

• Review the overall design of the classes involved. It might be necessary to reorganize responsibilities to achieve a more cohesive and loosely coupled design.

Use Interfaces or Abstract Classes:

• Consider using interfaces or abstract classes to define common behavior shared between classes. This allows for polymorphism and promotes more flexible and maintainable code.

Here’s a simple example illustrating Feature Envy:

To solve it, we can remove the responsibility of SoppingCart class to calculate the discount. It is a detail related to the product.

This refactoring adheres to the principles of encapsulation, as the Product class is responsible for its own discount calculation. It also makes the code more maintainable and reduces the dependency of the ShoppingCart class on the internal details of the Product class.

In this article, we explored some common code smells and their solutions. We discussed the importance of removing unnecessary comments, nested code blocks, inconsistent naming, and feature envy. These are just a few examples of code smells, and there are many more to consider. In the next article, we will continue our exploration of clean code principles and dive deeper into other code smells and how to refactor them. Stay tuned!

Continue reading Clean code — Does code smell? Part 3

References

• Martin, R. C. (2008). Clean Code: A Handbook of Agile Software Craftsmanship. Prentice Hall.
• Rodrigo Branas Clean Code YouTube Channel