Loose thoughts on code documentation

Anatoly Shalyto, a professor at Saint-Petersburg State University of Information Technology, Mechanics and Optics recently published an article about Foundation for Open Project Documentation. If you're interested in reading another set of philosophy about the importance of documentation in general, go ahead and read it. I didn't find the article itself very interesting or evolutionary, but it did give rise to a couple of thoughts.
First, I can't remember when I last saw a project that had a really admirable quality of documentation. If the user manual and installation instructions are well written, projects usually get praised… until somebody has to pick up the development ball after a three-year break during which the original code authors have switched jobs. Technical specifications are often limited to the few structural diagrams drawn during the analysis phase and a hastily sketched DB diagram/document that's roughly maintained throughout the project. Who said documentation is only for customers (or worse, end users)?
Second, I can't remember when I last saw a developer with a really documentation-oriented approach to software engineering. By "documentation-oriented" I refer to the desire (and discipline) to make sure that the brainwork is actually recorded in a reusable form. Writing good, readable code is an important step. Using proper design patterns helps, too. But does all this produce a really durable solution? Not without documentation. Not even the geekiest developer is better at reading C++ than plain English (or whatever your preferred language is).
Code-technical documentation – by which I mean documenting very simple issues such as namespace/class relations, chosen algorithms, design patterns and so on – has lately been very close to my heart. I'm certain I'll be returning to the subject sooner or later. When I look at f.e. Bugzilla, I see a huge need for somebody to explain the code structure in both diagrams and words. If we had a proper technical documentation, developing BZ would be so much easier for new people – and we'd probably have less bugs as well.
Until I've formulated another rant on some practical approaches in code documentation, I'm sticking with this motto: Mistakes in Word are cheaper than mistakes in Visual Studio. Feel free to substitute your favorite documentation/code editors. And I'll finish off with this citation from Shalyto's article: 'One of the pioneers of the aircraft D. Douglas said once – "when the weight of the documentation becomes equal to the weight of the airplane, it is ready to fly", and A. Martin affirms, that the documentation for the famous Boeing 747 weighed more, than the plane itself.'

September 12, 2004 В· Jouni Heikniemi В· One Comment
Posted in: Misc. programming

One Response

  1. Carlos Rogerio Camargo - August 2, 2021

    Hi,
    I am looking for technical texts of Switch Technology (or Automata-based Programming) written in English (developed by Prof. Dr. Shalytho. from ITMO); almost all resources that I found are written in Russian.
    Could you, please, help me, sending links to articles or books in English about that subject?
    thanks!

Leave a Reply