3 ms·

The example you gave should rather go into the code as a code comment. Esp. if it is only a hack, it is much better to give such a statement there instead of th

The example you gave should rather go into the code as a code comment. Esp. if it is only a hack, it is much better to give such a statement there instead of the commit comment. The commit comment should more be about what you have worked on and/or what you have completed or so. Btw., for a small team, the code comments itself may also be a good place to write the review comments into, maybe marked with a TODO or so. In both cases, you have the information right there where you may need it.

akkartik 16y ago
Code comments are best for spatially local concerns. Commit messages are best for temporally local concerns. Design decisions are temporally local concerns. "What if _" is something you just thought up today. Tomorrow you'll be concerned about other issues. A long code comment about something you don't care about will keep getting in the way.
nostrademons 16y ago
If every design discussion we had in the review comments ended up as a comment in the code, the comments would be 10x longer than the code. There's one CL that I'm currently reviewing where the review thread is 41 messages long. That's not all that atypical for changes that require any sort of design discussion. Though yeah, something that's a quick hack should have a " TODO(username): Fix hack. See review discussion in CL 12345678." to let the reader know that there's something else they should be aware of. Basically, I think the code comments should say what the code does (and be rather sparse, usually, because you should be able to tell from the code itself), the commit comment should say what the change does, and the reviewlog should say what the code doesn't, i.e. roads not taken, design alternatives considered and rejected, tradeoffs made. The code always doesn't do far more than it does; putting that in the code comments makes it harder to follow what the code does do.

akkartik 16y ago

Code comments are best for spatially local concerns. Commit messages are best for temporally local concerns. Design decisions are temporally local concerns. "What if _" is something you just thought up today. Tomorrow you'll be concerned about other issues. A long code comment about something you don't care about will keep getting in the way.

nostrademons 16y ago

If every design discussion we had in the review comments ended up as a comment in the code, the comments would be 10x longer than the code. There's one CL that I'm currently reviewing where the review thread is 41 messages long. That's not all that atypical for changes that require any sort of design discussion. Though yeah, something that's a quick hack should have a " TODO(username): Fix hack. See review discussion in CL 12345678." to let the reader know that there's something else they should be aware of. Basically, I think the code comments should say what the code does (and be rather sparse, usually, because you should be able to tell from the code itself), the commit comment should say what the change does, and the reviewlog should say what the code doesn't, i.e. roads not taken, design alternatives considered and rejected, tradeoffs made. The code always doesn't do far more than it does; putting that in the code comments makes it harder to follow what the code does do.