As we prepare to bring some new developers on board, it’s worth taking a look at a few of the things we do that make us successful. Sometimes we internalize these things and, not having had to explain them to anyone for a while, they kind of dissolve into habit. Or dissolve into habits we don’t think we need to practice anymore. Documenting our coding decisions is one of the reasons we can support so many customers with such a small team. It’s easy to overlook, but it works.
This is the second post in a series that formed the basis of my 2017 DevCon session on Increasing Code Quality While Staying Lean. Check out the first post for an introduction to the series. We’re looking at techniques that have made a big impact at SeedCode and we hope you’re inspired to incorporate some of these into your work.
Documenting Decisions – We’re Coding for Our Future Selves
We’re coding for our future selves—both in our products and in custom work. We end up coming back to our own code months later and sometimes it’s as opaque to us as if we’d never written it.
So when we make decisions, we want to document them so that our future selves (or our teammates) can more quickly pick up the thread when they return to our work.
This means you can restart projects more quickly, which in turn increases the delivery velocity: especially the velocity of delivering change requests and bug fixes.One definition of fragility: the original developer is the only one who can help this customer. Click To Tweet
Here’s what we do:
- When we comment out or change code in a script or in a calculation, we include a note in the comment about why we did it.
- If work is related to a Manuscript case, we include the case number in the comments: it’s amazing to be looking at an If() statement you don’t think should be there and see this telling you exactly why it’s there… “If filter is not empty and field DOES NOT match this source: Case 30325”. Now you can go read that case and see the real-world situation that required the If() statement.