User talk:Dmose:Code Comments

Sometimes when I get a review request, I end up asking the reviewer to go back and liberally add comments before I'll do the review. It makes me feel like sort of a jerk, because I suspect that folks think I do it to be pedantic or because I'm lazy. I'd like to try and explain my rationale here, because I think this is sensible thing to do, completely independent of any pedantic or lazy tendencies of mine.

There are two things that I think are relevant here:

• documenting code (and even individual variables) forces one to think in more detail about underlying assumptions. Moreover, it helps get the assumptions written down, so that people who touch the code in the future have a better feel for what they're dealing with. Documenting methods and attributes/variables provides a mini-API that both callers and implementers can attempt to match, and it makes it easier to see when new or existing code violates encapsulation, an assumption, or an invariant.

• if, as a reviewer with some knowledge of what's going on in the existing code, I can't fairly quickly read through new code and clearly see the purpose of each code clause, then future maintainers who have less context than I do are likely to have a really hard time. Indeed, individual code fragments are often obvious enough to not need commentary; the key is really commentary that makes it clear how the individual fragments fit into the overall code flow.

The point here is not to try and make an inappropriately low-level guideline that every single line of code needs commentary, but that the minimum level of commentary desired is that which makes the code easy to read and maintain.