Writing Understandable Source Code

Published: 2018-04-07
Updated: 2018-04-08
Web: https://fritzthecat-blog.blogspot.com/2018/04/writing-understandable-source-code.html

It's not a coincidence that it is called "code", which denotes unreadable text. What software developers write is mostly hard to understand. Consequence is that it is also hard to maintain. What is hard to maintain will be replaced, because time requires changes. Replacing means giving up concepts that worked well. Will the new version have better concepts, will it be understandable, how long will it last?

If you once followed a software product several years, you will know that maintenance effort outweighs writing new source code by far. Moreover new source code sets future trends. Thus writing understandable code is a question of to be or not to be.

Who Writes Code

Software is mostly written by people that consider themselves to be engineers or technicians. But in fact software development is something between journalism and engineering.

In times of libraries and code reuse a developer has to read lots of API documentations and source code before he/she can start to work and apply the acquired knowledge. The implementations afterwards will reflect that reading, so he/she is kind of a reporter that "brings things to application".

But was that applied API actually understandable? When not, you would have needed a really good programmer to get things done maintainable. Now, what means "good programmer"?

A Piece of Code

Following is about rainy weather, sitting at home, and handling the house's windows in case it is windy or calm. English Sunday business.

Written by person A:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

    private void handleWindowsAtRain()  {
        if (isWindy()) {
            closeUpwindWindows();

            if (smellInside())
                openDownwindWindows();
            else if (smellOutside())
                closeDownwindWindows();
        }
        else if (smellInside()) {
            openAllWindows();
        }
        else if (smellOutside()) {
            closeAllWindows();
        }
    }

And by person B:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

    private void manageInletsAtRain(Inlets inlets) {
        boolean am = airMoving();
        boolean si = smogInside();
        boolean so = smogOutside();

        if (am)
            disableLuv(inlets);

        if (am && si)
            enableLee(inlets);

        if (am && so)
            disableLee(inlets);

        if (!am && si)
            enableAll(inlets);
        
        if (!am && so)
            disableAll(inlets);
    }

Both sources do the same.

How long did you need to verify that?
Are you sure that you found out?

That's how developers spend their time.

Can we do better?

Dictionaries

For Business

If you don't have one, developers will use whatever comes to their mind currently. So make sure that it is

• "Window"
• and not "Inlet"

In reality I have seen business dictionaries very rarely. If you ask for it, you are directed to the source code mostly. So code explains itself from code?

For Technics

This would be to make sure that it is

• "open" and "close"
• and not "enable" and "disable"

To avoid misunderstandings: this is not that nouns are business and verbs are technical. Both could be on each side.

I have never seen a technical dictionary in reality. Developers are expected to all use the same terms, and to speak the same language, by means of their telepathy skills. Everybody knows the difference between "hidden" and "invisible" ... don't you?

By the way:

• if there is a business term that can replace the technical one, then use the business term!

Coding Directives

Yes, agreed, the first source snippet is the better one. Because its structure is logically clearer, and the wording is better. But how can you teach good coding style, and how check it? With reviews that last as long as writing the code lasted? Point the developers to thick books for which they will need a month to read, and a year to understand?

Question is if the second snippet isn't the better one, because it uses parameters instead of relying on class member fields. This makes code much more flexible for refactorings: Declare what you need to operate as parameter. Was this advice in the thick book you've been reading?

How can you convince developers that ...

.... are bad?

Common Sense

Finally it boils down to having good common sense. Agile programming demands it. People that are able to compromise, willing to spend time on discussions for finding good terms, and improve the old code that spells badly.

Code is not written by developers only, also business staff writes it. But whoever writes code does one thing:

• → connect technical and business logic

And that literally needs common sense.

Resume

A book that I really appreciate is Robert C. Martin's "Clean Code". It may be lengthy sometimes, and things may be missing, and it's a pity that it's not open source, but if you come over it, try to read from it as much as you can.

I can't give a definition of what makes a "good programmer". Maybe we shouldn't use the terms "good" and "bad" any more. What about "useful" and "confusing"?

• The useful people are those that document their source code, that can explain and present their concepts, in a way that everybody knows the context and can follow. Those that make sure that everybody is actually following. And they know that writing understandable code requires care and time.


• The confusing people are those that consider source code to be just the technical representation of "their" business, an unsolvable problem that will always leak, and thus it is not important to write understandable code, too expensive. All essential software is already written, we just need to build, deploy and sell it.

Don't write code for machines, write code for humans. Keep this in mind: "Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live."

ɔ⃝ Fritz Ritzberger, 2018-04-07