Frontier Software

Robert Laing's programing notes

By Robert Laing

We think in order to understand what we are doing. If we understand something, we can explain it clearly in writing. If we have not explained it in writing, then we do not know if we really understand it. — Leslie Lamport, Who Builds a House Without Drawing Blueprints?

This current incarnation of a domain I first registered in 2002 is an attempt to bring notes I’ve written and spread between github, a wiki, files on various computers… into one place where I can expand and polish it in a structured way.

Various hobby projects I’ve used as learning projects over the years include events listing site Joe Blog which is currently written Erlang, an AI strategy game site Newsgames which is written in SWI Prolog, and a simple JavaScript video game at Seatavern.

Writing reference material for my own code involves using a different tool for each programming language: Erlang has EDoc, SWI Prolog has PLDoc, and JavaScript has JSDoc.

These FooDoc tools use structured comments to create online reference material, a craft all programmers should learn. The last thing anyone debugging or refactoring a program wants is to scroll through dozens of lines of comments, and similarly coders using the documentation generated want quick answers to their problem.

The best guide I’ve encountered to create good structured comments is from a textbook freely available online, How to Design Programs, brought to life by a MooC I recommend highly by Gregor Kiczales. Good reference material comes naturally by getting into the habit of following How to Design Programs' six step design recipe.

The second step of the recipe, combines three steps Signature, Purpose Statement, Header, followed by a big step Functional Examples which enters the blurry intersection of documentation and unit testing. I wish more programming languages had an equivalent of Python’s doctest which encourages programmers to include examples in their documentation, and has a way to use these comments as unit tests.

To shelter novices from a cacophany of tools, How To Design Programs teaches a Lisp variant bundled with an integrated development environment Dr Racket. These structured comments are just comments in Racket since there’s no RacketDoc.

The title of the book could be shorted to How to Design, because it mainly stresses the importance of systematic thinking, which the epilogue explains applies to every profession. Designing involves thinking, and thinking involves writing (which may involve diagrams as much as text).

For a website like this, I want something where code is embedded into text rather than vice versa. Researching which of the bewildering selection of open source documentation tools I should pick, via Google I found this comparison of static site generators, which is part of a course Documenting APIs. A reason I’ve put so many links in my text is for me to keep a reference of all the online information I plan to go back and read in full one day.

I selected Hugo for this job largely based on the impressive number of code formats its syntax highlighting supports. Though written in Golang, Hugo serves a difference purppose to GoDoc, Go’s FooDoc reference material generator. I previously used Doxygen, which while primarily aimed at documenting software written in C++, supports a lot of languages — with the glaring ommission of JavaScript and other somewhat offbeat programming languages I use.

Last updated on 26 Oct 2019
Published on 23 Nov 2018

Content Footer