The idea of clean code has been circulating around the internet for a while now, and as most things in life, the longer they persist and travel around from person to person, the more meaning gets lost until it turns into something complete different then what was originally intended.
And that exact same thing is true for writing good solid "clean" code. You can read all kinds of books online about what exactly entails having clean code, and the specifications make perfect sense. For example.
- Easy to read
- Good naming conventions
- Small functions
- Fewer function arguments
- Less to no comments (really?)
And many more. And the thing is, all of these things sound good when you read about them, from a book written over a decade ago. This is exactly how I learned to code in college for the most part, as I built traversal algorithms and non-practical applications, such as maze traversal functions and stop-light simulators.
Here's the rub however. If you work in the corporate world, coding can be difficult. Requirements aren't clear and constantly changing. Code that is amazing today, is deleted tomorrow. And there are about 2-3 people with different opinions as to what clean-code is working on a single project sometimes. Some people might be happy go-lucky co-workers that take others into consideration when coding something. While others may exude passive aggressive behaviors as they await lunch-time and their work will show as such.
All is not lost however. We can still have some semblance of order in our coding environments, but we're going to have to restructure a bit what it means to have "clean-code". For one, it can't rely on having less code or smaller functions. That isn't a realistic approach. Logic is complex sometimes. Very complex. And this mainly depends on your business and its needs. Creating a sales order system is much different than creating a blog post. While we can work to modularize more, having "small" functions will become a subjective issue. A small function for a graphics engine could consist of hundreds of lines. While a "small" function on a card game, can equate to having 20-30 lines of code.
Less comments or no comments - I saw this requirement to clean code and immediately wanted to know the explanation behind it. The idea being that good code, does not require comments as it should be self-explanatory based on its naming convention and overall structure. And here is my gripe with that statement. Again, it goes back to the fact that real-world code is very complex and non-standard. There is no a->b-c->d road where everything just clicks into place and you get a promotion. Everything is a business these days, and as such, subject to change and sometimes even going against the normal standard is required in order to test things out. Let me give this example, somewhat based on a real-world scenario.
I was working on a massive data archiving script, in order to cut cost on my companies nightly data backups. In the process, I have to identify which records are either not required and can be deleted, or maybe just faulty records that are abandoned in order to clear those out. In this case, you are working with multiple servers across multiple databases and maybe even multiple networks. So redundancies and double and triple checks are a part of the code. Whenever you delete data, you have to take extra precautions, because one wrong delete, and your entire database can vanish in the blink of an eye and it could take a while for everything to get set back into place. These scenarios are not uncommon in the corporate world, particularly with large websites.
If a company requires a 100GB backup nightly for the database, then that is the requirement. And that's expensive, even today with cloud storage and cheaper storage mediums. Without comments in this scenario, you are going to inevitably cost some form of damage to the project and to the code. And once you decide to leave the company, that headache will befall some random person that walks through the door. So I commented that code, and heavily, because having a function named "DeleteUnused()" won't paint any picture at all as to what is happening or more importantly as to why it is happening.
Instead of not having comments, I'm all for the idea that clean code should have more comments. Well written and concise comments, identifiable by person and by date. Knowing that "Steve B." make that one change 2 weeks ago to your script is meaningful and important for you to be able to do your job correctly. And again, it is probably more important to the person that will be taking over your job one day.
Fewer function arguments - You can make a case for either / or on this one. Personally, I enjoy having a function that allows as many parameters as make sense to the functioning of it. Whether they are all used or not, is a whole different case. This is why I'm a big fan of C#'s ability to allow optional parameters into its function declarations. In this case, you create more arguments but you allow them to be optional when calling the functions. It's a more scalable approach overall and can allow for your functions to become powerful as you progress.
Perhaps these are personal coding choices and methods that I tend to follow and that I have picked up from years and years in software development. Which should further strengthen my point. And that is that programming is a somewhat personal thing. Everyone learns it differently and everyone has their own way of doing it and creating strict rules, such as "Never do this" and "Always avoid that", makes one question why these things were implemented in the first place if they are so terrible. Why do we allow comments in code? Should we remove then from all programming languages in an attempt to better force "clean code"?
And should we run down the list of "to do's" and enforce them in every programming language? We would have a giant list of functions with long descriptive names and less than 20 lines, pointing to other functions limited in parameters, forcing us to create objects for every single function request that we wished to make and to top everything off, we would have no comments to explain what on Earth is happening. Perhaps an exaggeration on the concept of clean code. But maybe not. I find many developers these days, who tend to sacrifice on the area of complexity and business logic, in exchange for less code and as such progression takes a slight pause as we navigate shaky waters.
So while not against the idea of having more readable and manageable code, by no means do I know the right approach for you to enforce it in your own personal or professional work life. Clean your code so that it makes sense to you and to your co-workers. Not because someone made a case for it 10 years ago during a whole different era in programming.
Walter Guevara is a software engineer, startup founder and currently teaches programming for a coding bootcamp. He is currently building things that don't yet exist.