"They won't be interested in looking at code. All they care about is the UI."
If you work professionally as a developer, I'm willing to bet that you've heard a statement like this. Most often, these phrases are spoken when it comes time for developers to demo features to non-technical stakeholders. I’d previously never given comments like this much thought, but I've come to realize that there is at least one subtle, yet deeply embedded problem with them—they’re rooted in the fact that the code is not able to be understood by its stakeholders.
Readable is not the same as understandable.
Source code readability seems to get all of the attention these days. Certainly there’s nothing wrong with that. Crafting readable code is absolutely essential to the health and sustainability of an application. There's no question about that. However, I'm now beginning to question if the focus on readability has caused us to assert that code is understandable just because it's readable. Thus, I think it's important to note that there is a difference between code that is readable and code that is understandable.
Readable has more to do with the physical structure and layout of the code. In fact, the very definition of readability is the property of type that affects the ease with which printed matter can be read for a sustained period. So, things like proper spacing and short functions are what affect readability. Readability lays the foundation for understandability.
Understandable has more to do with the content rather than the actual structure of the text. For example, given the following two code snippets that perform the same operation, which one would you say is more understandable?
Doctor doctor = new Doctor();
doctor.getPatientRecords(patientId);
or
Doctor dr = new Doctor();
dr.getData(pId);
Given two code snippets with the exact same structure, the first is more understandable simply because of the names that were chosen for the method and variables. Since the names are explicit, anyone can immediately read this code and know that the doctor object is retrieving patient records by the patient ID. The second snippet may look familiar because it follows a convention that is common to many codebases. Though common, someone who reads it for the first time will not know exactly what's going on.
So, who should be able to understand the code?
If you're developing software as a part of a team, any member of the team should.
When a developer who is unfamiliar with the code looks at it for the first time, the code should clearly express its behaviors. If the developer has to inquire, "What's going on here?" that's a possible sign that the code might not be as understandable as you thought. Make it a habit to become sensitized to this and make appropriate enhancements when necessary.
Don't forget about non-technical stakeholders. Start being open to showing non-technical stakeholders your code. Will the names that you've chosen for your classes, methods, and variables bear any resemblance to the verbiage that they use to describe what the application should do? It's often pretty trivial to change names. So, why not be willing to use ones that everyone can agree on?
When non-technical stakeholders are able to gain a high-level understanding of what’s going on in the code, they will likely be more able to add important perspectives and insights based on their operational knowledge and expertise. When this happens, it can help the application to improve in many more ways.
At the end of the day, all professional software developers have an obligation to write the best software possible. When anyone on the team truly understands how the software is working, they can offer more appropriate suggestions and solutions. The end result: better, higher-quality software.
