I am open-sourcing the code for usdlc. Courtesy requires me to check the code and add comments before checking it in. I have long maintained that self-documenting code is a myth. The best laid out code in the world may tell you the how and what, but it is much harder to record the why.
Forget that others may have to work with or use your code. Forget the maintenance team in the distant future. Just think about yourself. How often have you updated or refactored your own code only to remove a feature that you later found necessary? How often have you puzzled over code you wrote a week ago asking “Why did I write it that way”.
I keep that perspective when I am commenting my code. In particular anywhere I needed to take time to solve a problem I add a comment. I too often revisit that problem (or one similar) again and can’t remember the path to the solution. For this reason I don’t just comment the class and method entry points – but also add comments wherever the code is less than clear about intent or reason.
I don’t comment when I am writing. It gets in the way of the thought processes required. More importantly, discovery means I will change a lot of code during this time. Comments can get out-dated and not removed. I comment just before check-in when the problems and resolutions are still fresh, but I am commenting stable and tested code.