When the why behind code is missing
“Misc optimizations”
“Updates”
When documentation is missing, you only have the code to go by. Even if the original author is available, they may not remember why they wrote something the way they did. Even if you are the original author.
It makes debugging harder than it could be. Do better by documenting whatever you discover, even for code you didn’t write.
You can use pull request templates to remind and standardize. I like a version-control-agnostic commit template of:
“Fix for BUGID_URL: “Bug ticket title” {What I found}. {How I fixed it}. {Notes for the future}.”
I include the bug ticket title because it saves switching to the web browser, and the bug database may not be accessible in the future.
You can also implement automated mandatory adherence to commit messages and templates. What has worked for you?