In a presentation for MarkupUK 2019 called Documenting XML structures, I introduced the term “knowledge bubble” (https://markupuk.org/2019/webhelp/index.html#ar12.html). What I meant is that when you’re busy doing something complicated, like programming, it’s very hard to imagine what people on the outside don’t know or will understand. You’re in the middle of it now and everything is therefore understood and crystal clear.
You have to acknowledge to yourself that you’re in a knowledge bubble during development. And being in a knowledge bubble means it’s impossible to write good documentation because you don’t really realize what the reader doesn’t know. This is not only true for documenting things (in separate documentation), but also for writing good code comments and judging code comprehensibility.
So how can we overcome this obstacle? Here’s how I try do this:
I write my software with in the back of my mind that I will come back to it later. That makes it OK (and not laziness) to flag missing comments and sometimes missing non-essential pieces of code with a TBD marker (or whatever you want to use meaning To Be Done).
Adding these TBD markers is important so you won’t forget or overlook anything later. Writing a function but not feeling like adding the descriptive header comment? Add a comment with TBD. Having to write some error handling code that is not essential during initial development? Add a comment saying TBD. I think you get the picture.
Find some time, later that week, maybe after a weekend, to review your code and fill in the TBDs. Try to do it when the knowledge bubble has deflated to a reasonable size (so not immediately after finishing coding).
Even if the code is flawless (which never happens), you’ll be astonished what you find with regard to comprehensibility issues.
Key is that after you think you’re done programming, take a pause/break/weekend/vacation/cup of tea and always revise/review what you’ve written. And also: important commenting is best left to review time.