Category Archives: documentation

Great Documentation, Great Software

A paraphrased conversation, the other day, between me and a customer of one of my customers: Me: Are you experienced at working with my customer’s developer APIs? Them: I always feel like a newbie, because there’s so much stuff. But … Continue reading

Posted in architecture of sorts, documentation | Leave a comment

Let’s talk about self-documenting code

You think your code is self-documenting. That it doesn’t need comments or Doxygen or little diagrams, because it’s clear from the code what it does. I do not think that that is true. Even if your reader has at least … Continue reading

Posted in advancement of the self, architecture of sorts, documentation | 8 Comments

All the things

It’s been a long time since I had a side project, or one that didn’t get abandoned very early on. I tend to get sidetracked by other thoughts about computing, or think “while I’m doing this, I’m leaving that unsolved” … Continue reading

Posted in advancement of the self, documentation, learning, techradar | Leave a comment

Today’s surprisingly short workflow-improving win

When I have a TODO comment (or a #error in code, which is how I frequently do TODOs), I switched to writing the commit message I want to be able to use when I’ve fixed the TODO. Then I write … Continue reading

Posted in code-level, documentation | Leave a comment

On what makes a “good” comment

I have previously discussed the readability of code: The author must decide who will read the code, and how to convey the important information to those readers. The reader must analyse the code in terms of how it satisfies this … Continue reading

Posted in documentation | 1 Comment


Barely 4,000 years ago, documents were written on heavy, clay tablets. The Epic of Gilgamesh, one of the earliest known works of fiction, was written on 11 such tablets with a 12th added later. There was only one thing you … Continue reading

Posted in books, documentation, Talk | Leave a comment

Specifications for interchanging objects

One of the interesting aspects of Smalltalk and similar languages including Objective-C and Ruby is that while the object model exposes a hierarchy of classes, consumers of objects in these environments are free to ignore the position of the object … Continue reading

Posted in documentation, OOP, software-engineering, TDD, tool-support | 1 Comment

The Liskov Citation Principle

In her keynote speech at QCon London 2013 on The Power of Abstraction, Barbara Liskov referred to several papers contemporary with her work on abstract data types. I’ve collected these references and found links to free copies of the articles … Continue reading

Posted in code-level, documentation, OOP, software-engineering, Talk | 2 Comments

Does that thing you like doing actually work?

Genuine question. I’ve written before about Test-Driven Development, and I’m sure some of you practice it: can you show evidence that it’s better than (or, for that matter, evidence that it’s worse than) some other practice? Statistically significant evidence? How … Continue reading

Posted in advancement of the self, documentation, software-engineering | Comments Off on Does that thing you like doing actually work?

I made a web!

That is, I made a C program using the literate programming tool, CWEB. The product it outputs is, almost by definition, self-documenting, so find out about the algorithm and how I built it by reading the PDF. This post is … Continue reading

Posted in code-level, documentation, tool-support | Comments Off on I made a web!