One of the things that I most enjoy about programming is that it is a constant learning experience. The field is ever changing and will never get stale. There’s always something new to learn, such as new languages or technologies that bring increasingly new levels of innovation to the field.
After years of experience as a software developer, I recently decided to read Robert Martin’s book “Clean Code: A Handbook of Agile Software Craftsmanship” and it was like walking down memory lane. A lot of the mistakes referenced, I have either seen or made myself early on in my career. Thankfully, however, I had great mentors and teammates to learn from throughout my career and who served as great guides on my career path. Now, as a software architect, I recommend this book to all software developers, but just in case you don’t get to read it right away, here are my 5 top lessons learned from reading the book.
1. Use Meaningful Names
Your variables, functions, classes, etc. should always have easily understandable names. Take your time with naming. If you feel that you need a comment to explain what a variable represents or what a function does, then you probably haven’t chosen the correct name. Choose names that reveal intent.
2. Comment Wisely
Have you ever read a comment that explained things perfectly and then went and looked at the code and realized it no longer did what the comment said? That’s because comments can easily become outdated, despite constant updates to code. Avoid using comments that explain what the code is doing whenever possible. Instead rely on rule #1 to have function names that are self-explanatory. Not all comments are bad, but you should not use comments to make up for messy code. Use comments to explain the purpose of why the code exists.
3. Single Responsibility Principle
Functions should be small and they should do one thing. If you need to scroll to read the full content of the function, then your function is doing too much and it can be broken down into smaller functions that do one thing. Classes should have a single purpose for existing and should be responsible for only part of the functionality, having only one reason to be changed. If your class is doing too much then it will be changed constantly as you work to fix separate functionality. You want other developers to know right away what your class is doing rather than having to dive in to understand a multipurpose class.
4. Clean Up Your Code
Literally clean it. Don’t comment-out old code because you are afraid to delete it. All development teams should have source control by now and you will be able to go back to view prior code if the need arises. If you just comment out old code instead of deleting it, others will then be afraid to delete it because they assume you left it there for a reason, and things can get pretty messy.
5. The Boy Scout Rule: Leave the campground cleaner than you found it
This rule should be your most important goal. When you commit code you should feel proud of what you delivered and you should not be part of the problem. If you are dreading a code review, then you probably didn’t spend enough time cleaning up your code. You should strive to improve existing code. You don’t need to do huge refactors but maybe rename a confusing variable or at least remove unused variables or imports that someone left behind.
We constantly go to our scrum meeting and hear statuses like “I’m done; I just need to test the code”. The problem is that once you test it and the issue is fixed, you are not ready to commit the code. Sometimes you’re just so happy to get things working that you want to deliver the fix right away, or just feel the pressure to finish your work as fast as possible, but you are not done. Take a look at the code you are about to deliver. Do you understand it? Will you understand it in six months? Will your teammates understand it? Did you take the time to clean up your code? You need to fight the urge to deliver fast sloppy code and take an extra hour or two and deliver quality code that you won’t have to revisit.
And, while everyone says they will, do they really come back to fix the code once it’s delivered? One of the common mistakes I see is that developers fix the code, and once the issue is fixed, they move on to the next big thing and forget to go back to clean it. Don’t be that developer; be the model scout.
As Robert Martin so eloquently states in his book, “One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king. Professionals use their powers for good and write code that others can understand.”
