We have all written our fair share of “bad code” at some point in time, however unintentional it might be, developers understand we get it. These cinematic scenes always popup in a similar fashion.
I have this deliverable to complete so I will make it work first, THEN I will refactor the code, i.e make it “clean”.
Consequently, time ran out as it usually does and you didn’t get a chance to refactor the code you wanted. Time was later spent on doing some other task, like documentation….*sips tea*.
The plot thickens.
It has been 3 releases since and now you’ve completely forgotten to refactor the code. Maybe you’ve little by little snuck in fixes apart of each commit, come on don’t tell me you haven’t fixed something that wasn’t in a ticket before, live a little. Perhaps, there has been so much functionality baked on top of it that you’ve completely settled for what’s not broken don’t touch it mantra. Whatever the case might be at some point in your career as a software practitioner you have neglected a best practice for one reason or another resulting in bad code.
Maybe to the best of your abilities, you thought you were writing the world’s greatest algorithm only to look back at it after a few months to question if you had written this in the first place. You simply didn’t know you were writing bad code. Only after requirements change, as they often do, you are now forced to change 1 thing in 10 different places.
In this article, we will discuss:
- What is clean code
- Cons of bad code
- Habits to avoid to write clean code
- Clean coding practices
we can use to keep our code cleaner, more readable and easier to maintain.
What is Clean Code?
Bjarne Stroustrup, inventor of C++ and author of The C++ Programming Language:
I like my code to be elegant and efficient. The logic should be straightforward to make it hard for bugs to hide, the dependencies minimal to ease maintenance, error handling complete according to an articulated strategy, and performance close to optimal so as not to tempt people to make the code messy with unprincipled optimizations. Clean code does one thing well.
Grady Booch, author of Object Oriented Analysis and Design with Applications:
“Clean code is simple and direct. Clean code reads like well-written prose. Clean code never obscures the designer’s intent but rather is full of crisp abstractions and straightforward lines of control.”
These are some of the examples of the definition of “Clean Code” from some of the most respected authors in software development topics.
From those definitions coupled with my own coding experience, I would say clean code is, RUM.
- Easy to Read
- Easy to Understand
- Easy to Modify
It must be welcoming to the eyes and have good taste you know, like well-aged wine or rum. Well structured, elegant and ever so effervescent.
Cons of Bad Code
It’s a common case in software development projects where we find developers prefer to re-write a project or start from the beginning. That’s because software is harder to read than it is to write. It is just difficult to maintain on a whole really. However, this stigma is not just because of the difficulty in nature that comes with maintaining legacy systems, coupled with all the classes and methods you have to know about and understand but also whether good programming practices were implemented in the first place. The more complex a project is, the harder it becomes to work with it.
Not using clean coding practices every chance you get will result in an incredibly costly problem in the future. The result of this can be seen impacting both developers and the company.
For the developer, this results in:
- Little to no motivation and lack of enthusiasm
- More time spent on understanding than to do the actual implementation
- Reluctant to learn new technologies for the project
- Accidentally introducing new bugs
For the company, this results in:
- Missed deadlines
- Delayed product launches
- High rotation of “unskilled” developers
- Difficulty in keeping up with the competition
Habits to Avoid to Write Clean Code
“We become what we repeatedly do.” ― Sean Covey
Let’s face it, habits are hard to develop and they are even harder to break. What’s done repeatedly over time no longer becomes a trade-off or one-off scenario. It now becomes you, it now becomes what you do automatically when the pressure arrives and the workload tumbles in, we revert to the default. So it’s important to avoid bad habits not only in our professional lives and work but also in all other areas. I find myself too guilty of these bad habits and constantly look for ways to curb them.
These are some of the bad habits I find that contributes to poor coding practices.
I will fix it later
I love this one, it’s one of my favorites. Saying “I will fix it later” results in it never being fixed because so often time truly runs out and you didn’t get a chance to do it. It is better to try and fix it right there and then at all times. // TODO: comments also help to keep a better track of future intentions, use them wisely.
Creating one-line solutions
Also one of my favorites. Creating complex expressions that only takes up 1 line but 100 columns is a clear sign of poor programming practice. It’s a normal habit to try and make several lines of code and combination of functions into 2 or 3 lines instead but this makes it difficult to read and understand.
Ignoring things
You know that inside voice that pops up that says, “that shouldn’t be there” or “I need to catch that error waiting to happen”. Yah, sweeping it under the rug. Until an error eventually comes up and it now becomes more challenging to fix. As they are many ways to sweep things under the rug to avoid these error-prone habits at all cost. Don’t just catch an exception, handle it.
Refusing to write bad code
Deadlines are on the horizon, you tried warning the client or manager about the consequences but they are relentless as ever. So now you’re forced to make a deliverable that cannot wait for a clean solution. However, be versatile enough to quickly come up with a testable solution that involves the best practices and ignore the urge to rush.
These are just some of the most popular habits I believe contribute to poor coding practices. There are so many factors not just in coding but also in things like teamwork, giving feedback, project planning that then trickles down into coding.
Clean Coding Practices
We have reviewed how bad codes are created and why it is important to write clean code. Now let’s look at some of the best practices we can implement to ensure our software remains maintainable.
Meaningful Names
It’s pretty hard to write software without naming something. Everything has a name; classes, methods, variables, source files, you name it. Naming is one of the most common issues developers face in coding. Declaring variables like String s might seem clever and easy to do but they make it more difficult to understand. Imagine the thought that goes into naming our babies, that’s what we want in coding. Good names make it cleaner and easier to read. Here are a few points to consider when creating a name.
Use Intent-Revealing Names
Names should reveal their purpose and don’t leave the developers guessing what it was created for or what kind of data it is storing. Good names save time in coding just as how good names on babies save time in counseling. Your project team will thank you for it.
Bad: String fn: // user first name
Good: String firstName;
Avoid Hard Names
Avoid names that are hard to pronounce. Instead, writing clear abbreviations might be worth it. The name is not as long as you think it is.
Bad: Date genymdhms;
Good: Date generationTimestamp;
Make Distinctions
Make an obvious and deliberate distinction in naming variables. Compilers disallow the use of duplicated names so developers might find the urge to only create names that will satisfy the compiler. It’s not sufficient enough to only add noise words, numbers or characters to distinguish two or more variables.
Bad: int accountId, accountId1
Class Names
Classes and objects should have nouns and be camel-cased. Avoid class names that are verbs.
Method Names
Methods names should have verbs like getEmployee, updateEmployee.
Functions
Now let’s look at creating functions and the best practices we can consider when creating them.
Small
Functions should be small; like super small and after you have made them small….go make them even smaller. Ant-man shouldn’t have anything on your functions when you’re done.
Do One Thing
Because of how small they should be, the idea behind this is that they should have one singular focus. Functions should do one thing and they should do it very well.
Reduce Arguments
You should strive to reduce the number of arguments a function takes. Functions should have no more than 3 arguments if possible.
No Side Effects
This is a little tricky as it might not be as obvious to identify. However, if we keep our practice of singular focus and extreme smallest, we should be able to identify side effects in functions and remove them. Side effects occur when your function promises to do one thing and does another hidden thing that was not communicated. Let’s look at what a side effect looks like. Let’s review the image taken from the book “Clean Code” by Robert C. Martin Series.
Can you identify the side effect? It calls the function Session.initialize(); even tho the function name says it only checkPassword. This function is misleading in functionality and alters the state based on some condition.
Comments
Don’t use comments wildly as functions often change and the comments are left to be updated. Comments that are not updated give miss leading information about the current version of the function. Instead, of using comments to document bad code, rewrite it.
I would say a good rule to follow when it comes to commenting is, don’t use comments when you can use the actual code to document your intent.
Keeping it DRY
DRY, stands for Don’t Repeat Yourself. The main idea behind writing dry coding is to save time and money and keep the project maintainable. By having one instance of the code around bug fixing and refactoring becomes 10 times easier. However, while keeping it DRY it’s very important not to do this in a manner where code becomes complex and hard to read.
Conclusion
In this article, we have gone through a number of best practices that we can implement to make our coding skills a little better. Knowing the right thing to do is one thing, but doing the right thing is another, do the right thing. Also, the book on Clean Code by Robert C. Martin is a must-read which provides much more details on topics covered in this article.
References:
- Clean Code: A Handbook of Agile Software Craftsmanship
- Clean code… Why bother?
- How to write Clean Code?
- Is Your Code DRY or WET?
- The Cost of Bad Code, and Preventing it
