Write Clean Code
Writing clean code is what you must do in order to call yourself a professional.
Code smells are coding patterns that hint that a problem is present. Introducing or not removing such patterns is bad practice, as they decrease the maintainability of code.
Boy Scouts have a rule that says, “Always leave the code better than you found it”. Applying the Boy Scout rule to software development means that once you are writing or modifying a piece of code, you have the opportunity to make small improvements as well. The result is that you leave the code cleaner and more maintainable than you found it. If you are adjusting a piece of code now, apparently there is a need for maintaining it. That increases the chance that you will revisit that same code later. When you revisit that code again, you will benefit from the refactoring you are doing now.
How to Apply the Guideline
Leave no unit-level code smells behind.
Leave no bad comments behind.
Leave no code in comments behind.
Leave no dead code behind.
Leave no long identifier names behind.
Leave no magic constants behind.
Leave no badly handled exceptions behind.
See details in the sections: The key principles of clean code.
Common Objections to Writing Clean Code
Objection: Comments Are Our Documentation
“We use comments to document the workings of the code.”
Comments that tell the truth can be a valuable aid to less experienced developers who want to understand how a piece of code works. In practice, however, most comments in code lie—not on purpose, of course, but comments often tell an outdated version of the truth. Outdated comments become more and more common as the system gets older. Keeping comments in sync with code is a task that requires precision and a lot of times is overlooked during maintenance.
Code that “tells the story” itself does not require lengthy comments to document its workings. By keeping units small and simple, and by using descriptive names for identifiers, using comments for documentation is seldom necessary.
Objection: Exception Handling Causes Code Additions
“Implementing exception classes forces me to add a lot of extra code without visible benefits.”
Exception handling is an important part of defensive programming: coding to prevent unstable situations and unpredictable system behavior. Anticipating unstable situations means trying to foresee what can go wrong. This does indeed add to the burden of analysis and coding. However, this is an investment. The benefits of exception handling may not be visible now, but they definitely will prove valuable in preventing and absorbing unstable situations in the future.
By defining exceptions, you are documenting and safeguarding your assumptions. They can later be adjusted when circumstances change.
Objection: Why Only These Coding Guidelines?
“We use a much longer list of coding conventions and quality checks in our team. This list of seven seems like an arbitrary selection with many important omissions.”
Having more guidelines and checks than the seven in this chapter is of course not a problem. These seven rules are the ones we consider the most important for writing maintainable code and the ones that should be adhered to by every member on the development team. A risk of having many guidelines and checks is that developers can be overwhelmed by them and focus their efforts on the less critical issues. However, teams are obviously allowed to extend this list with items that they find indispensable for building a maintainable system.
Last updated