In the Zone

(Ugh! I forgot to post this last week. My apologies)

English: Two programmers
English: Two programmers (Photo credit: Wikipedia)

Programming, as I’ve probably said before is a strange occupation. You start with a blank sheet, steal bits and pieces from where ever you can find them and glue them together modify them, add some bits of original (to you) code and try to think of all the possible ways your program can go wrong.

Then you try and break your code (and usually succeed at first). Programming is still very much an art form. Of course things have changed a lot over the years, and we are able to use the work of others to help us in our endeavours, but my first paragraph is still true.

This image was selected as a picture of the we...
This image was selected as a picture of the week on the Farsi Wikipedia for the 13th week, 2011. (Photo credit: Wikipedia)

In the beginning there was “Hello World”. This is probably the simplest program that does something visible. It doesn’t take any information in and its output, the words “Hello” and “World” are not very useful in themselves. Actually, I’d say that there is an even simpler program that takes no input, produces no output, and in the process changes nothing. A “null” program if you like.

A programmer writing a new program may well jump in and start coding by grabbing some other code that he or she has access to, but that stolen code was developed, ultimately, from “Hello World” or the null program.

Picture of "hello world" in C by Use...
Picture of “hello world” in C by User:aarchiba. (Photo credit: Wikipedia)

A good programmer is one who steals code from elsewhere and modifies it to do what he or she wants. There is no stigma of plagiarism attached to this process, and it is in fact strongly encouraged that programmers share code. A spoof news item that I came across stated that all programming courses would be replaced with a course on how to find code on “Stack Overflow“.  I’ve been unable to find the link again, but I believe that the item was on “The Onion“, a well known satirical website.

Of course, such a  process may propagate errors or bugs across many programs, but it is such an effective strategy that it is used more often than not. If code exists to solve a problem then it would be silly to pass it by and write it ones self, maybe introducing bugs to the code. The advantage of “borrowing” code is that while errors and bugs may be in the borrowed code, many eyes will have looked at the code and there is nothing more that programmers like than pointing out bugs in the code of other programmers.

Wheel bugs mating
Wheel bugs mating (Photo credit: Wikipedia)

Stack Overflow allows anyone to post code and comment (up to a point), so code posted may not be top quality, but other programmers are quick to jump if they see bugs or inefficiencies in code. Contributors will also point out code which doesn’t follow standards or conventions in the programming language being used. This is considered useful, as the code, if modified, can be accessed and understood more easily, and may often be safer and free of more bugs than unconventional code.


Embed from Getty Images

When a program is written it starts out as literally a few lines of code or even an empty file. Any programmer knows that a program grows swiftly and in ways that can’t be foreseen until it may be of enormous size. It won’t be all written in one sitting but is usually written in stages. I personally like to write my programs in very small chunks, building on what has gone before. I think that many programmers use this process, though there may be others who write a sizeable chunk of code before testing it.

Ah, testing! Testing is the less enthralling parts of writing programs. Any program must be tested, to ensure that it does all that is required and nothing else. Generally the program being written doesn’t do all that is required and does things that shouldn’t happen, and initially it is likely to crash or produce cryptic error messages under some conditions.


Embed from Getty Images

Testing is supposed to reduce the number of such unwanted happenings, and the programmer may do some rudimentary testing and may handle at least some errors. However the programmer will realise that users who are unfamiliar with how the program is written may well do something that he has not expected.

So clever people have developed ways of automatically testing programs. To do this they have had to write the programs that are used to test programs. And of course those testing programs may have bugs. You can see where that leads to!

Zebra (programming language)
Zebra (programming language) (Photo credit: Wikipedia)

When a programmer knows a programming language really well, he is able to literally think in that language. The word “literally” has been devalued in recent time, but I am using it in the true sense of the word. This is hard for some people to understand as they think of language as something like French or Tagalog, and they can’t understand how one can think in a programming language, which is qualitatively different from a spoken language.

An interesting thing happens when a true programmer is programming something. His thought processes become so involved in the process of programming and in thinking in the programming language that he loses track of the outside world. That’s why programmers are whimsically thought to subsist on fizzy energy drinks and dialled in pizza. It is because those things are easily acquired and the programmer can keep programming.


Embed from Getty Images

A programmer “in the zone” is so embedded in the world of the program that he or she may often be reluctant to leave that world and respond to irritations like bodily needs and colleagues. I doubt that there is a real programmer who has not surfaced from a deep dive into the depths of a programming problem and realised that all his colleagues have left and it is late at night or very early in the morning. That’s the reason programmers stay after all other people have left – they know that they can slay the current bug with just a few more changes and a few more runs of the program.

The zone has similarities to the state of meditation. While meditation is passive though, programming is an active state. In both cases the person basically disconnects from the world, so far as he or she can, and the concentration is directed internally. Now that I think about it, any deep thought, be it meditation, programming, or philosophising, even playing a sport at a very high level, needs such concentration that much of the world is disregarded and the exponent enters the zone.


Embed from Getty Images

Documentation

Script Installer documentation page
Script Installer documentation page (Photo credit: Wikipedia)

Documentation. The “D word” to programmers. In an ideal world programs would document themselves, but this is not an ideal world, though some programmers have attempted to write programs to automatically document program for them. I wonder what the documentation is like for such programs?

gcc unter kde
gcc unter kde (Photo credit: Wikipedia)

To be sure if you write a program for yourself and expect that no one else will ever look at it, then documentation, if any, is up to you. I find myself leaving little notes in my code to remind my future self why I coded something in a particular way.

Such informal documentation can be amusing and maybe frustrating at times. When reading someone else’s informal documentation such as “I’m not sure how this works” or “I don’t remember why I did this but it is necessary”. More frequently there will be comments like “Finish this bit later” or the even more cryptic “Fix this bit later”. Why? What is wrong with it? Who knows?

English: A bug in mathJax
English: A bug in mathJax (Photo credit: Wikipedia)

The problem with such informal in code documentation is that you have to think what the person reading the code will want to know at this stage. Add to this the fact that when adding the comments the programmer is probably focussing on what he/she will be coding next, the comments are likely to be terse.

Add to this the fact that code may be changed but the comments often are note. The comment says “increment month number” while the code actually decrements it. Duh! A variable called “end_of_month” is inexplicably used as an index to an array or something.

English: Program Hello World Česky: Program He...
English: Program Hello World Česky: Program Hello World (Photo credit: Wikipedia)

Anyone who has ever done any programming to a level deeper than the usual beginner’s “Hello World!” program will know that each and every programmer has tricks which they use when coding, and that such tricks get passed from programmer to programmer with the result that a newcomer looking at code may be bamboozled by it. The comments in the code won’t help much.


Embed from Getty Images

Of course such programming tricks may be specific to the programming language used. While the same task may be achieved by similar means at a high level, the lower level of code will be significantly different. While that may seem to impose another barrier to understanding, I’ve found that it is usually reasonably easy to work out what is going on in a program, even if you don’t “speak” that particular language, and the comments may even help!

While internal documentation is hit and miss, external documentation is often even more problematic. If the programmer is forced to write documents about his programs, you will probably find that the external documentation is incomplete, inaccurate or so terse it is of little help in understanding the program.

English: Diagram of the mechanism of using per...
English: Diagram of the mechanism of using perl modules. Deutsch: Diagramm des Mechanismus der Verwendung von Perl-Modulen (Photo credit: Wikipedia)

In my experience each programmer will document his/her programs differently. Programmers like to program so will spend the least possible amount of time on documentation. He/she will only include what he/she thinks is important, and of course, the programmer is employed to program, so he/she might get dragged away to write some code and conveniently forgets to return to the documentation.

If the programmer is at all interested in the documentation, and some are, he/she will no doubt organise it as he/she thinks fit. Using a template or model might help in this respect, but the programmer may add too much detail to the documentation – a flowchart may spread to several pages or more, and such flowcharts be confusing and the source of much frustrated page turning.

Lava lamp flowchart
Lava lamp flowchart (Photo credit: Wikipedia)

Of course there are standards for documentation, but perhaps the best documentation of a program would be to specify the inputs and specify the outputs and then a description of how the one becomes the other at a high level. As I mentioned above a programmer will probably give too much detail of how inputs become outputs.

Documentation tends to “decay” over time, as changes are made to the program and rarely is the documentation revisited, so the users of the program may need to fill in the gaps – “Oh yes, the documentation says that need to provide the data in that format, but in fact that was changed two years ago, and we now need the data in this format”.

Legacy of the Ancients
Legacy of the Ancients (Photo credit: Wikipedia)

The problem is worse if the programmer has moved on and gone to work elsewhere. Programmers tend to focus on the job in hand, to write the program to do the job required and then move on to the next programming task, so such code comments as there are will be written at the time that the programmer is writing them. Such comments are likely notes to the programmer him/herself about the issues at the time that the program is being written.


Embed from Getty Images

So you get comments like “Create the app object” when the programmer wants a way to collect the relevant information about the data he/she is processing. Very often that is all that one gets from the programmer! No indication about why the object is needed or what it comprises. The programmer knows, but he/she doesn’t feel the need to share the information, because he/she doesn’t think about the next person to pick up the code.

English: Picture of an ancient pipe documentin...
English: Picture of an ancient pipe documenting the foundation of student fraternity Guestphalia Bonn (Photo credit: Wikipedia)

I don’t want to give the impression that I think that documentation is a bad thing. I’m just pondering the topic and giving a few ideas on why documentation, as a rule, sucks. As you can imagine, this was sparked by some bad/missing documentation that I was looking for.

Open source software is particularly bad at this as the programmer has an urge to get his program out there and no equal urge to document it. After all, a user can look at the code, can’t he/she? Of he/she could look at the code, but it is tricky to do so for large programs which will probably be split into dozens of smaller ones, and the user has to be at least a passable programmer him/herself to make sense of it. Few users are.

Screenshot of the open source JAVA game Ninja ...
Screenshot of the open source JAVA game Ninja Quest X (I am one of the programmers) (Photo credit: Wikipedia)

So I go looking for documentation for version 3.2 of something and find only incomplete documentation for version 2.7 of it.  I also know that big changes occurred in the move from the second version of the program to the third undocumented version. Ah well, there’s always the forums. Hopefully there will be others who have gone through the pain of migration from the second version to the third version and who can fill in the gaps in documentation too.

Parse tree of Python code with inset tokenization
Parse tree of Python code with inset tokenization (Photo credit: Wikipedia)