Published April 16, 2020
by Doug Klugh

Communicate

Write code in a way that makes it easy to read and easy to understand.  Reading code is an inevitable part of maintaining and extending an existing code base.  Since developers spend much more time reading code than they do writing it, writing readable code contributes greatly to productivity.  Applying many of the prior DevTips will help to achieve effective abstraction, encapsulation, and Separation of Concerns that will greatly promote readability.

A software craftsman strives to effectively communicate (through code).  When you write code, you're not simply directing a computer, you're communicating the organization and the intent of the software with your coworkers and even with your future self.  If it takes considerable time to understand what the code does, it is not well written.  And poorly written software is not of high quality.  It will lack maintainability, extensibility, and testability — which will increase technical debt and decrease the value of the software.

Writing readable code takes skill.  You must be able to implement functionality in a variety of ways to be skilled at promoting readability.  Achieving Separation of Concerns (SoC) goes a long way in producing code that conforms to cognitive limits¹.  A developer should not have to know how an object is implemented to understand its intent or even to reuse it.  Otherwise, encapsulation is broken.  And without encapsulation, the code is not object-oriented — it is procedural.  Code without encapsulation lacks abstraction — which makes understanding the code that much more difficult.

Another effective method for achieving SoC is through Command-Query Separation.  This principle formulates a constraint on the way you write code and is an effective method for managing side effects within your code by controlling how and where they occur.  In simple terms, this principle states that if methods change state, they should not return values.  And if they return values, they should not change state.  While that sounds pretty straightforward, it takes practice to apply it effectively.

In order to write good code you must be able to implement a requirement in more than one way.  So how do you learn how to implement features in different ways?  Like everything else...  practice.  Code Kata are a great way to develop your development skills.  They are repeated exercises that are designed to improve and eventually perfect the skills and discipline required to become a good developer — a craftsman.

Do not take readability for granted.  Code that is easier to read and easier to understand is also easier to maintain, easier to extend, and easier to test.  It is well worth the effort and makes your team more productive.  And it will make you look like you actually know how to write good code.  :-)