APPropriate Behaviour
The book about all the things software writers do that aren't writing software.
FSF
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
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
Meta-writing
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!
