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".