Clean Code
Let me dedicate this post to write about the topic of coding style and share my opinion about Clean Code. I will conclude with a useful definition to check when the code is really clean.
I think that the way one should write the code has the purpose of achieving maintainable code rather than working code. For instance, if you look at HAND_LNK_DBG (the good one) you see, in the beginning, the code generated after the command a. This code is enriched with comments that make it understandable and maintainable. In the last part of the file, you see the code generated after the command u. This very last past is exactly what the CPU reads, understands and executes. This second part is an example of working code which is not maintainable. One may write exactly the same sequence of mnemonics (as produced by the command u) in the beginning part soon after the command a and obtain the same working code but this would be not understandable at all. And if it is not understandable, it is also not maintainable. In my personal hobby experience, I write fragments of code in my spare time, and I come back to the same procedure left at 30% of completion after one week or more and I try to continue from that point onwards. I need to comment as much as I can, in order to be able to find myself again at every restart and continue.
Talking about maintainability of code, I found a very nice sentence on the internet which says "Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live"1. Sometimes this sentence is associated with the topic of Clean Code. This famous aphorism seems to say everything in the right way, but at a second look, I see that it considers two different people: the author of the code and a second person which is the maintainer of the code. Typically between these two persons, there is a geographical distance and a time distance (the time distance is the most relevant in my opinion). But what if the two persons were the same person indeed? What if the distance that separates me, or you from the moment when we start writing code, to the moment when we finish it was just a lot of time in between? In the end, I think that a good coding style is not a kind of generosity towards a different person that might use your code, but a big favour that you do to yourself. Finally, I discover that I write comments for myself. This diary (and the blog) is like a huge comment that I am writing for myself in order to keep track of the learning steps along the way.
Let me spend some few words about the topic of Clean Code. All the few lines just above this one, they explain why writing Clean Code is so important. The google search engine returns over 2.3 trillion results if you search it. Among these results, there are books written about this topic too. I made myself an idea about all those trillions of results, and the idea is that everyone understands what he/she thinks is right about Clean Code and even tries to explain his/her opinion to what Clean Code should be with examples and so on. The truth is that there is no clear definition of Clean Code and meanwhile the tag Clean Code and the aforementioned aphorism seem to say everything, in reality, they say nothing. Everybody can legitimately state that he/she understood what Clean Code is and that his/her interpretation is the right one. In the meanwhile, I did a little bit of practice and I can formulate the definition of Clean Code: "The code is clean when by printing it on paper, one can read and immediately understand exactly what is going on in the code without any need of actually running the code step-by-step with help of an IDE or debugger".
From this definition, it descends why one has to stay within the 80 characters
per line of code. Otherwise, one ends up with a very bad format which
sometimes is even no longer readable when the code is printed on paper.
From this definition descends why the programmer cannot over nest statements.
Otherwise, nobody will understand the effects of such nested statements on
paper. To see what they do, one must then use an IDE or debugger to go over
the heavily nested statements step by step and figure it out what the effect
is.
Then I paused, reflected and asked myself, why such a definition came to my
mind. I think that I am currently following a very hard path, which is very
close to the one that the programmes in the '70 and '80 had. There was no
Integrated Development Environment at that time and you had to work with just
text files that went thru an assembling and linking stage at the command line.
All you get as feedbacks were errors and warnings together with a line number
from the assembles and the linker. Compared to them, I am in a similar
situation. In the end, when I cast any piece of software that I run
immediately on the real PC (for instance a new SOFTWARE.BIG) then I feel
"alone in the dark" (just to quote a video game). I am alone because
when the PC is booted with my software I have nothing that can tell me what is
going on and, more often than I like, I seat in front of the black screen of a
non-responding PC (in which case, I have to reboot).
Back to the times of the programmes in the '70 and '80, it was self-evident
that the code has to stay within 80 chars per line. This was all the screen
that one could see at that time, and it was also the printable length of a
line of text. There was no need to state that you have to stay within 80 char
per line as well as there was no need to say that the code hat to be
self-evident when printed on a piece of paper without the need of an
Integrated Development Environment because there wasn't any at that time. In
other terms, there was no need to say what Clean Code was because
producing Clean Code was, more or less, the way to work at that
time. The programmer had no alternative else but writing clear self-explanatory
and well-commented code that once printed on paper one could follow along with
the error and warning messages coming from assembler and linker and spot the
problem. By the way, I realized that I can spot errors on the same very code
once it is written on paper meanwhile I couldn’t see them on the screen (and
this has nothing to do with the quality of the screen).
So if Clean Code was embedded without explicitly being aware of it
in the working tools and manner of that time, then why and when the need and
urge of Clean Code born?
In my opinion, it is all about the Integrated Development Environment. The
IDEs are very good and take a lot of overhead (and over headaches...) for the
programmer away. IDEs help a huge step to increase speed and productivity in
creating code so these IDEs are a very good thing. Some are better than others
and everyone has his/her own opinion about the favourite or best IDE, but in
general, IDEs are a good thing. Meanwhile, you can do without them, it is
better to have and use one. The flip side is that, since IDEs are too good,
we, the programmers, get lazier and lazier. IDEs don't constraint us to stay
within 80 chars per line of code (until the point comes that you need to print
your code and you get a mess out of the printer). IDEs integrate a
step-by-step debugger so the programmers don't think that it is necessary, at
many places in the code, to write comments at all. Inside the step-by-step you
do see what happen, so why one would write a comment to describe what is
visible inside the debugger of the IDE? Furthermore, thanks to IDEs, the
programmers tend to write super-dry and super-nested statements that by just
reading without stepping through them one can never really be 100% sure and
say what the exact outcome is going to be. In conclusion, and in my personal
opinion, the easiness of coding with an IDE rose the problem a working code
but hard to read and bad maintainable. Then, this rose the need and the urge
to state that the code must also be Clean and not just
Working Code.
Let me add some few words about the coding style. As long as you achieve a
code that once printed on paper is self-explanatory and clear then every style
is good. However how the style looks like depends on the programming language
(a suitable coding style for Python maybe be unusable with assembly and vice
versa), and the tools as well. Let us look at and keep the assembly as
language and consider different tools. Assembler such as MASM and NASM let you
label addresses and DEBUG.EXE doesn't let you do that. The fact that DEBUG.EXE
doesn’t let you label the addresses but you have to write them and keep
updating all addresses for jumps and strings, makes me prefer backwards jumps
against forwards jumps for the simple reason that backwards jumps are towards
known addresses and forward jumps not (so I cannot tell where to jump until I
write lines of code ahead). For the same very reason I prefer to write in
DEBUG.EXE all my "data section" before the
"code section" because, in this way, when I need to point a string,
this just happens to be backwards in address space hence at an already known
address that I can immediately use. As a consequence, you cannot derive a
unique coding style for assembly that fits both MASM and DEBUG.EXE. More in
general, you can neither derive a unique coding style that fits each
programming language nor do it for the same programming language and different
tools.
The conclusion is, as you can see, that you cannot learn
Clean Code by learning a coding style and tell that if you use
such a style then you obtain Clean Code. However, there are books
that just try to teach you a coding style and pretend this is the job of
explaining and teaching what Clean Code really is. In my opinion,
this is wrong.
In my opinion, the only right way is to look at the output of any code style
of any language and check it against the definition. If you can print it on
paper without messing up with the format and you can be 100% sure about what
is going on in the code without actually running it in the IDE then you have
Clean Code, otherwise not.
I want to conclude with an image: writing Clean Code is NOT like cooking. While cooking, you make your tools and the kitchen dirty and you clean afterwards. When cooking, this is the right way to do it. When you write a program instead, you write it straightforward Clean. "Clean Code" is a state of mind: either you make it while writing, or you don't make your code clean afterwards.
Comments
Post a Comment