What is good code

Good code, is readable code

Home



I have been programming for a long time and have already written and read quite a few lines of code. But in the course of your career as a programmer you will always stumble across a problem that prompts you to learn something new, even if it's just something banal like enumerations.

I had the following problem: There was a variable or routine that should only be able to assume two states, the alignment of a page number on a page, either centered on the page or on the outer edge of the page. You can work with whole numbers: 0 for centered and 1 for the outer edge. But that's not entirely satisfactory, because after a while you don't know which number stands for what. And an outsider certainly doesn't know. This solution would be as good as illegible, hardly maintainable and very error-prone, because what happens if someone hands over two or three or minus four? So we have two problems: 1. readability of the code and 2. susceptibility to errors.

Let's look at point one and take a Windows function: CreateEvent:

HANDLE WINAPI CreateEvent (LPSECURITY_ATTRIBUTES lpEventAttributes, BOOL bManualReset, BOOL bInitialState, LPCTSTR lpName);

The two Boolean parameters are problematic here. It is not clear what the effect of betting on true or false is. If the first is set to true, do I have a manual reset or not? And what is the difference between a true and a false initialization status? It only helps to look up help. A little help is the code completion of the IDE, but you don't always have it at hand (in a forum, an e-mail, if you look at the code in a simple editor, as a printout or with an overhead projector). And often times you don't write the code yourself, you just read it. In this case, it would be better to use enumeration types with, for example, the values: MANUEL_RESET and AUTO_RESET, then everything would be clear when reading. The same procedure could be used for the second Boolean parameter.

Let's come back to my specific problem. It took a while, but I finally came up with a good solution. Afterwards I was a little annoyed that it took me so long to do this, even though I had it in front of my nose the whole time: The solution is a list. A list as used by the VCL, for example, to align a paragraph in a TMemo: taCenter, taLeftJustify, taRightJustify. With the enumeration you have your own data type with a given range and named constants, if you will. So a solution in Delphi would look like this:

type TPageNumberAlignment = (paCenter, paLeft, paRight); procedure SetPageNumberAlignment (Alignment: TPageNumberAlignment); begin case Alignment of paCenter: ShowMessage ('centered'); paLeft: ShowMessage ('left'); paRight: ShowMessage ('right'); end; end; procedure TForm1.Button1Click (Sender: TObject); begin SetPageNumberAlignment (paCenter); end;

With this we solved both of our problems in one fell swoop: The code is readable and it is no longer prone to errors, since only exactly three values ​​of a certain data type can now be transferred.

So you can see that a readable code also produces good code in most cases. Hence the principle: "Design for readability". Or roughly in German: "Design for readability". If you orient yourself to this principle when programming, a second principle arises by itself: "As few comments as possible, as many as necessary." You should only comment on what cannot be seen in the code. There is no need to comment on the incrementing of a variable, if you read the code you can see what is happening. Whereas, on the other hand, the why might make sense.

The question that remains to be answered is how to write readable, good code. I think you can't really learn that. The only thing that really helps is experience that you have acquired over the years and reading and studying foreign code. Although, sometimes you don't even have to wander far away. Often it is enough to look at old code again after a year or two. If you understand it without thinking about how it works, what it does and why it was solved this way and not another way, then it was good code. Otherwise it could use some revision. Donald Edwin Knuth's advice may also help:

Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

Or to put it in the words of the Pascal inventor, Niklaus Wirth:

Programs should be written and polished until they acquire publication quality.

2010-12-29T23: 44: 48 +0100