Writing code is an art unto itself, but writing clean code that is both maintainable and still makes sense is a skill that requires practice. I tend to focus too much on getting my code to work rather than being able to understand it at a later time. After reflecting on a couple of articles about clean code and code smells, I’ve identified some practices I’d like to adopt more often—and some habits I want to avoid.
What is Clean Code?
According to Soyak (2024), clean code is code that is “well-organized, easily understandable, and maintainable.” Writing clean code isn’t just about making it functional—it’s about ensuring that anyone (including your future self) can understand and modify it without undue effort. Soyak highlights several key principles, including:
- Define variables close to where they are used.
- Group closely related functions near each other.
- Keep code lines short and focused.
- Avoid horizontal alignment (lining up code across lines).
I’ve often aligned lines of code or comments because I find it visually pleasing. However, as Soyak points out, this practice can introduce unnecessary complexity. Misaligned spacing in different editors or environments can make the code look disorganized and can introduce problems down the line. Here’s an example:
# Bad
variable1 = 10
variable2 = 20
total_value = variable1 + variable2
# Good
variable1 = 10
variable2 = 20
total_value = variable1 + variable2
One other area I want to improve is grouping related functions near each other. In the past, I would simply list functions in the order I wrote them, making it harder to find and update related logic. By grouping functions logically, I can navigate and refactor my code more easily, especially in larger projects. For example:
# Grouped Functions
def validate_user(user):
# Validation logic here
def save_user_to_db(user):
# Database logic here
def send_welcome_email(user):
# Email logic here
What are Code Smells?
On the other end of the spectrum you have code smells. Code smells, according to Kanjilal (2022), is code that is “inefficient, nonperformant, complex, and difficult to change and maintain.” These bad practices don’t necessarily break functionality, but they indicate deeper problems that could grow over time. Common examples include:
- Duplicate code
- Long methods
- Over-reliance on comments
- Data clumps
Duplicate code can creep in as projects grow, especially when I’m in a hurry to implement features. However, duplicating logic wastes time and makes maintenance harder. Instead, I want to reuse existing functions whenever possible. By reusing functions, I can avoid redundancy and reduce the risk of inconsistencies during updates.
Another thing I’d like to avoid are unnecessary or long comments. I try to comment my code so that I can understand what I was thinking when I wrote it, but the line between too much comments and not enough can get a little blurry.
# Unnecessary comment
count = len(users) # This counts the number of users
# Self-documenting code
user_count = len(users)
Conclusion
By adopting clean code practices and avoiding common code smells, I can write software that is easier to read, maintain, and improve over time. I plan to focus on grouping related functions, avoiding horizontal alignment, eliminating duplicate code, and using meaningful names instead of excessive comments. Writing clean code isn’t just about following rules—it’s about building a foundation for better collaboration and future-proof projects.
References
Soyak, T. (2024, April 28). Clean Code: Definition and Principles — Part 3 (Last Part). Medium. https://medium.com/@tahsinsoyakk/clean-code-definition-and-principles-part-3-last-part-5a247d957c79
Kanjilal, J. (2022, March 11). Understanding code smells and how refactoring can help. Search Software Quality. https://www.techtarget.com/searchsoftwarequality/tip/Understanding-code-smells-and-how-refactoring-can-help