Behind my desk and under it are hundreds of pounds of books on programming. There are the usual suspects: language books, textbooks, hardware documentation, how to run software teams, and then there are the books that talk about software craftsmanship.
Programmers get into the field either from a specific starting platform or language, usually to accomplish something right in front of them - I want to tweak Minecraft, I need to fix DOS, WordPress isn’t doing the thing I want. It’s code sure, but operative in the way Excel equations total expenses. They aren’t about mathematics. It’s only later on that programmers start thinking about platforms and languages agnostically.
So we come to books such as Code Complete, Clean Code, The Pragmatic Programmer, Refactoring, Domain-Driven Design, The Practice of Programming, Growing Object-Oriented Software Guided by Tests, and Design Patterns.
I own all these books and others. They’ve helped me a lot, however, these books and every rockstar programmer have never suggested what every English teacher has told you - journal every day.
Journaling is typically thought of as - what did I do today? Nothing against this of course. Folks write down what they learned, what they did well, what they could have done better, what they’re excited for tomorrow. All great, but not what concerns me.
Another approach for programmers is to log your progress through issues. Keep track of every step you make through a problem - your false starts, the line numbers affected, links to documentation related to the problem at hand, comments on improvements / future refactoring, places where you made decisions that involved technical choices versus financial / time pressures, and then narrate it all.
The log becomes your consciousness as you go and it serves a few purposes. First, it allows you to go back and get in your head space when you were last working on a section of code; second, if you happen to get abducted by aliens, someone can follow where you left off; third, it forces you to justify your actions to yourself and others in the future.
If you are explaining the issue to yourself, you are essentially trying to explain it generally, which means you can anticipate questions, concerns, and identify areas where you need to research more.
Programmers have this tendency to be way too declarative as if one problem had only one solution, while at any decent level of complexity, naturally there will be multiple solutions. Just like a doctor or lawyer, by logging you are building a case for your approach. And it begs the question - have you really thought about why you approached the problem in the way you did?
When you’re starting out, programmers can get focused on just seeing issues move across the Jira board. When they move on past that, work might move into sufficient stability with impressive speed. Past that, coding might be implementing what seems sufficiently complex to merit either awe from the younglings or depth that no one is really patient enough to investigate your decisions.
When you journal your decisions, none of these are acceptable.
To make logging even more disciplined, share your log with your team (we do this here at Greyland). This will expose your thought process and research, which enriches everyone, and encourages everyone to do likewise, even if no one ever reads it.
In the future you may be a overseeing a complex systems, with billions on the line, and people’s future and lives in the balance - wouldn’t you like to be practiced at explaining yourself?