Knowledge capture

Knowledge is highly ephemeral. In order to write a piece of code, you usually have to assemble a jumble of knowledge and keep it in your mind while writing the code. As soon as you are done, that knowledge will decay quickly. A good example is what happens when you are interrupted while programming. It can take minutes or hours reestablishing the mental context required to finish what you were doing before being interrupted.

Writing software is about capturing and usefully encoding knowledge. Which means that the code you write should aim to make life easier for your audience. An audience that will almost always include yourself.

If you have a tricky bit of logic or structure in your program, don’t just take the easy route and deal with it in the quickest way possible. Take care to encode knowledge meaningfully. For instance encapsulating it by creating a new type, class or whatever abstraction your language of choice offers. Then write tests that prove that the code works while providing additional instructions on how to use that knowledge.

If you are writing a piece of code to operate on some obscure and perhaps complex piece of data, create a data type (class, struct etc) for that data with operations that are meaningful for a user who sees the data type as a black box. When documenting it, take care to document it from the perspective of someone using the data type. Don’t get hung up on your struggle to write the code; nobody actually cares about that as much as you and the implementation isn’t as important as the knowledge encapsulated in, and expressed by, an abstraction.

You will have just one shot at capturing the knowledge: while you are writing the code.