The Maintainer

Last week I talked about some principles for developers. Today I want to drill down into the Code For the Maintainer idea. As developers we really like to work on green-field projects. There’s room to explore and innovate, and you don’t need to worry about pesky things like backward compatibility and existing user expectations. However, most of the work we do isn’t green-field. We work inside existing systems, adding functionality and fixing bugs. We extend them into new operational domains. In those cases we act as a maintainer of code, rewriting/refactoring existing code. That’s where this principle becomes really important, because the first thing you need to do, before you even think about doing what you came for, is to understand not only what the code actually does, but what the author’s intent was. So one of your jobs, as the writer of code, is to make the job of the maintainer easier. Make sure things are named well (they do what they’re called and nothing else). Make sure the flow is broken down into manageable chunks. Avoid side-effects. Even more than documenting the “What”, make sure to document the “Why” and the constraints/expectations.

And please, please, please, document how to setup/install and use any additional tools/permissions/preconditions necessary to build and work with the code. Even better, write a script and put it in the README.md. You do have one of those, don’t you?

You never know who’s going to look at the code 6 months from now. How many times have you looked at some code and asked what noob wrote it, only to run git blame and find out it was you? Do everyone a favor and write for the maintainer. I, and future you, thank you for it. As Ward Cunningham said:

“Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.”And his follow-up

I usually maintain my own code, so the “as if” is true.

https://www.joelonsoftware.com/2005/05/11/making-wrong-code-look-wrong/