Beautiful Code: Documenting Source Code

An article, authored by Adam Kolawa, in the book Beautiful Code, uses the subroutine SGBSV from the CERN mathematical library, written in Fortran, as example. The function comment block covers almost 2 pages of the book. The executable lines of code take up barely half a page! As Adam says, "One of the first things to notice in the code for the SGBSV routine is that it starts with a long comment that describes the routines purpose and use. In fact, the comment is exactly the same as the manual page for that routine".

Two statements that specially resonated with me:

• "If you cannot tell what the code does by glancing at the naming convention and several code lines, then the code is too complicated".
• "I hate reading code that was written to show off the developer's knowledge of the language, and I shouldn't need to go through 25 files before I can really understand what a piece is really doing".

Needed "Renovation"
Personally, I consider SGBSV - or any of the other names in the function - fails the test mentioned in the first quote above. But I suppose it makes sense to people who use the CERN mathematical library. Considering Fortran 90 permits names with 31 characters, I think the routines need to be "renovated".

Beautiful Code: Testing a Binary Search Implementation

The Binary Search algorithm has been around for quite a while. I remember doing an implementation (in Fortran) as part of course work in 1977. Hence it was a surprise to read about it in Joshua Bloch's blog post. I am  pretty sure that what I, and the rest of the course, implemented had the same defect.

Alberto Savola in his essay "Beautiful Tests" in Beautiful Code, quotes Donald Knuth as saying that though the first binary search was published in 1946, it took 12 more years for the first binary search without bugs to be published. However, defective implementations could, and did recur.

All very humbling. To quote Joshua, "The general lesson that I take away from this bug is humility".

Alberto Savola's piece uses the Binary Search program to show how tests should be developed. Here are some topics that I found educative:

• The utility of smoke tests.
• Re-factoring code to improve testability. A side-effect of this is to improve the design and the readability of the program.
• The design of tests to verify that neither a true condition is detected as false nor a false condition detected as true. What in radar theory are called failed detection and false alarm.
• Formulating theories (I think calling them hypotheses, would be more appropriate) of the forms: If A is true then B should be true; If A is not true then B should not be true. 
• Random generation of tests. This is most intriguing. I wonder if genetic algorithms could be used to generate tests.
• The use of helper tests that give an alternate way of checking. These are simple tests whose correctness are easy to verify by visual inspection. For the binary search a test using a linear search is also implemented. The linear search is used to cross check results obtained using the binary search.

A quote from Savola:
"Truly beautiful testing requires a developer to make an effort, think outside the box, explore weird scenarios, look for weaknesses, and try to break things".
(Note 1: The emphasis is mine.
Note 2: A side note: "outside the box", I think, is a more appropriate expression, in such contexts, rather than the more commonly used "out of the box".)

Beautiful Code: ABC, Ruby & Churchill

One of the essays in the book Beautiful code is titled, "Treating Code as an Essay". The author is Yukihiro Matsumoto. Yukihiro is the creator of Ruby.

Here are some quotes from the essay:
1. "The style in which they are written is just as important as their purpose. Both essays and lines of code are meant - before all else - to be understood by human beings".
2. "Unreadable code will reduce most people's productivity significantly. On the other hand easily understandable code will increase it. And we see beauty in such code".
3. "Brevity is one element that helps make code beautiful".
4. "Simplicity ... We often see beauty in simple code. If a program is hard to understand, it cannot be considered beautiful".

As an example of brevity he gives the HelloWorld program in Java and in Ruby. In Ruby just the statement, "print "Hello World\n" constitutes the complete program!

However, I do find it hard to accept, "The real shortcut for elegant code is to chose an elegant programming language. Ruby and other lightweight languages like it support this approach". This is like saying English is more elegant than Kanji - or the other way around. What can be more elegant than substituting a couple of lines of English with a few brush strokes!

The book has an essay where the code is in Fortran, another where it is in Lisp. Obviously if the program is math intensive, Fortran is the lightweight language. If the application is AI, Lisp, I presume, will be the lightweight language.

No matter what the language, I believe the qualities mentioned by Mr. Matsumoto will characterize beautiful code.

Of course code should not become Haiku:-)

But Haiku is poetry. Code should be like good tight prose.

Consider what Churchill called the moral of his six volume "The Second World War" : "In War: Resolution, In Defeat: Defiance, In Victory: Magnanimity, In Peace: Goodwill". How's that for minimal brush-strokes?

Beautiful Code

That's the title of a book edited by Andy Oram & Greg Wilson. I am currently reading it.

I believe that writing good code is akin to writing good prose. The ABCs of writing prose - Accuracy, Brevity, Clarity - are applicable to writing good code.

Consider Subroto Bagchi's valedictory speech at IIMB. Observe how:

• each episode (function?) supports a single value/moral (a function should do only one thing, and do it well?),
• simply constructed each sentence(each line of code?) is,
• the episodes are sequenced (sequence of function calls?),
• all the episodes support the purpose of the talk (the deliverable functionality?).

Code - like prose - has to be engineered. Well engineered artifacts are beautiful. It takes art to create them.

Apple's Software Process

Apparently Apple's Software Process has some problems. See Michael Barr's post.

Ah well! Apple is famed for cool products. Can quality processes qualify as cool? Well ... :-)