Intro
Welcome back everyone and hope that you’re having a great 2025 so far! Today, I wanted to take some time to talk about good and bad coding principles, as I am someone that likes to be as thorough as possible to make sure that anyone of any skill level can read and understand the code that I write. Through exploring the philosophies of Clean Code which was a book written by Robert C. Martin, and Code Smells which was popularized by Kent Beck, I feel that these two philosophies of writing code can help with reaching the goal of making my code accessible to anyone that is extending my code or understanding my code.
This code smells bad…
Let us start with our exploration into Code Smells. When programmers work on an application, we tend to see a few patterns or the way we structured our code that need to be refactored, like repeating code (not following the DRY principle) or code that is dependent on other code. Now these aren’t bugs by any means but can signify weakness in the design of an application and might increase the risk of bugs and program failure in the future if not addressed now. These patterns are what programmers call Code Smells and there are two main types of them being Within Classes and Between Classes.
NOTE: I will not be covering everything between the two types as that would make this blog post unnecessarily long, but I will cover some code smells and provide code examples. For a more in-depth explanation and examples of code smells, you can check [1] in the citations section.
Let us start Within Classes and expand our scope from there. One of the easiest examples of a code smell that may seem counterintuitive is code comments, as they can be proof that the code is not self-documenting to the programmer reading the code. Take the example below to validate an age in python:
This code is not self documenting as it is both hard to look at the way the validate_age function calculates the age passed in but to make it more self documenting, you can split up a lot of the functionality into named functions that describe the code being written:
Ain’t that pretty on the eyes now! While not the only Within Class code smell, it sure is an important one that makes a world of difference.
Onto the Between Class code smells with Data Classes. Data Classes are classes that just store data and has no methods to manipulate that data within it. Let us say that you have a Temperature class and want it to store data only, then you would do something like this:
But what happens when you want to update the temperatures in the Temperature class? Well then you have to make that global function to operate on data which smells a little too much like rotten fish to me 🤢. Data classes are not always a bad practice, as they can be important in being a clear structure to hold data when transferring data between systems and when you are implementing the “separation of concerns” principle where data structures like Temperature and actual code logic are stored separately. However, you need to make sure that when you are using a data class that should have behavior, like updating the temperature in this case, that the class is then developed with methods in mind to do such a task and not have the code else where so we can update the code to look like:
This smells like a much better cooked cod to me than anything else😃.
But we can make it clean(er) again!
- When talking about clean code, it is not always easy to discern what someone is talking about because certain people have certain standards when it comes to how they define their code as clean. However, Robert C. Martin wrote a book about certain conventions, standards, and practices that are still used today to determine the cleanliness of how source code looks. Assessing a code base for following clean code standards is a little tricky but you can tell if a coding project follows these conventions for clean code through aspects like
- Effectiveness, Efficiency, and Simplicity
- We first want to make sure that the code solves the issue that it was set out to solve, then if it does so efficiently, lastly if the solution is done in a simple manner.
- Format and Syntax
- The main point here is really to just make sure that the format of indentation and consistent syntax across the entire project is paramount here. For python, you can think of PEP8 being the sort of style guide you need for your code to follow.
- Naming
- Naming variables and functions clearly and descriptively can help developers quickly understand what the variable or function is doing, and how it is related to the rest of the code.
- Conciseness versus Clarity
- When developing code, you need to be careful to strike a balance between the two as concise code improves readability and maintainability, but it being equally important to ensure that the code is clear and easy to understand as over concise code can interfere with the readability of code.
- Reusability
- Reusability is all about improving the efficiency and productivity of development by reducing the amount of code that needs to be written and tested.
- Having a Clear Flow of Execution
- Making sure that your code follows a clear and logical structure makes it is less prone to errors, and easier to modify and extend which makes it more efficient in terms of time and resources in the long run.
- Using the Single Responsibility Principle
- This principle states that each class or module should have only one reason to change. You can think of this as making sure that a function is only doing one step to your solution.
- Having a “Single Source of Truth”
- This principle means that there is only one place where a particular piece of data or configuration is stored in the codebase, and any other references to it in the code refer back to that one source. Think of an API key. This is important because it ensures that the data is consistent and avoids duplication and inconsistency.
- Only Exposing and Consuming the Information you need
- This principle is more important when you are working around with objects, as you should only extract and use the specific data you need rather than passing around entire objects. Exposing and Consuming the information you need is best for the efficiency of the application in the long run.
- Modularization
- Basically just make sure that you’re breaking down large, complex code into smaller, more manageable modules or functions as it makes the code easier to understand, test, and maintain.
- Project Structure
- A well-organized project structure helps developers find and modify code easily, reduces code complexity, and improves project scalability and maintainability. Think about using directory names like
build,src,test, etc.
- A well-organized project structure helps developers find and modify code easily, reduces code complexity, and improves project scalability and maintainability. Think about using directory names like
- Documentation
- This is probably one of the most important parts to me, as I have been on the receiving end of bad documentation MANY times in my software development journey. When code is well-documented, it can save time and effort in debugging and maintaining the code so proper code comments and outside documentation that describes code flow is important.
All Clean!
Thank you for reading until the end of this blog post! I had a lot of fascinating moments of learning about these principles and how I want to use them in the future with my current Senior Software Development Project. Specifically Modularization of my code, as I have been writing a lot of code that works first and need to refactor it soon so that I can follow the best principles for the rest of this project.
Citations
[1] GeeksforGeeks. “Code Smell – A General Introduction and it”, Geeksforgeeks, 08 Sep. 2020. Available: https://geeksforgeeks.org/code-smell-a-general-introduction-and-its-type/.
[2] G. Cocca, “How to Write Clean Code – Tips and Best Practices (Full Handbook)”, freeCodeCamp, 15 May. 2023. Available: https://freecodecamp.org/news/how-to-write-clean-code/.