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