Re:Linus Torvalds: 'I Do No Coding Any More'
by BurningFrog on Sunday July 05, 2020 @01:07PM
(#23740165)
The maybe most common problem with programmer comments or commit message is what I call "Assumed Context".
When you spend a few days deep in a problem, it's very easy to explain the finer details of it while forgetting the big picture of what does this module even do, what real world problem were we fixing, etc, because that has become completely self evident to you.
It's a bit like giving a street address without saying what city it's in.
I have trained myself to look at both code and comments in a "what if I was a new hire 6 months from now" mode, and it's an indispensable tool for me.
When you spend a few days deep in a problem, it's very easy to explain the finer details of it while forgetting the big picture of what does this module even do, what real world problem were we fixing, etc, because that has become completely self evident to you.
It's a bit like giving a street address without saying what city it's in.
I have trained myself to look at both code and comments in a "what if I was a new hire 6 months from now" mode, and it's an indispensable tool for me.