How to self document your code for the next poor person who has to use it, fix it, or sell it

What Do Self-Documenting Software and Doors Have in Common?

Living Documentation — Part 2

Self-documentation — is documentation in a suitable form, typically label, signs, or simple instructions embedded, attached, or nearby to the device. This allows the device to be used, operated, changed, and repaired by following the instructions without having to hunt for some other form of documentation.

For those of you that think DOORS is some sort of new operating system or methodology then prepare to be amused. I thought it would be fun to explain what self-documentation is, and various styles through examples. The easiest device and familiar to us all is a door. The standard operation and use of a door are known to everyone however self-documentation can be essential in certain situations. In the following images each door has explicit documentation or implicit description, that are summarised in the titles. As you view each one try and contemplate what the equivalent “label, sign, or documentation” would be in the world of software source code.