3 ms·

Yea, but watch how soon it becomes outdated as the file changes.

by sridca 8y ago

YorkianTones 8y ago
This. Documentation (comment blocks in code, as well as all other forms of documentation) tends to become outdated because it is not maintained in sync with every code change. Solution: write clear, simple, modular code that is self-documenting and does not need extensive commenting.
atulatul 8y ago
Overall liked the original post. But also liked what you said. But here are a couple of Martin Fowler quotes (from his Refactoring book) I tend to follow: “A heuristic we follow is that whenever we feel the need to comment something, we write a method instead.” “Whenever I have to think to understand what the code is doing, I ask myself if I can refactor the code to make that understanding more immediately apparent.” https://www.goodreads.com/author/quotes/25215.Martin_Fowler https://www.goodreads.com/author/quotes/25215.Martin_Fowler
TeMPOraL 8y ago
How soon? I've rarely seen it happen in a meaningful way (i.e. other than someone using automated refactoring on some name, and breaking some comment reference that wasn't written in a way the autorefactor tool could read). When it happens and you see it, you should fix it like any other bug. Key trick is writing comments as close as possible to the code they affect. Then it's hard to miss affected comments if one's not doing a shoddy job.
- tome 8y ago
  I've done it frequently myself when I've changed a line that I originally wrote myself in a way that invalidates a comment written directly above.
- dllthomas 8y ago
  > Key trick is writing comments as close as possible to the code they affect. Then it's hard to miss affected comments if one's not doing a shoddy job. That also helps it show up in a PR so it may be caught in code review. Even so, IME comments get missed enough that over time I can't be as confident as we'd like that they match the code. I think it's also worth calling out that this key trick is not being applied in the recommendation up-thread, which asks for a block comment at the top of the module.
garmaine 8y ago
Reject pull requests that don't update the documentation (and tests).

Yea, but watch how soon it becomes outdated as the file changes.

by sridca 8y ago

Yea, but watch how soon it becomes outdated as the file changes.

This. Documentation (comment blocks in code, as well as all other forms of documentation) tends to become outdated because it is not maintained in sync with every code change. Solution: write clear, simple, modular code that is self-documenting and does not need extensive commenting.

atulatul 8y ago

Overall liked the original post. But also liked what you said. But here are a couple of Martin Fowler quotes (from his Refactoring book) I tend to follow: “A heuristic we follow is that whenever we feel the need to comment something, we write a method instead.” “Whenever I have to think to understand what the code is doing, I ask myself if I can refactor the code to make that understanding more immediately apparent.” https://www.goodreads.com/author/quotes/25215.Martin_Fowler https://www.goodreads.com/author/quotes/25215.Martin_Fowler

TeMPOraL 8y ago

How soon? I've rarely seen it happen in a meaningful way (i.e. other than someone using automated refactoring on some name, and breaking some comment reference that wasn't written in a way the autorefactor tool could read). When it happens and you see it, you should fix it like any other bug. Key trick is writing comments as close as possible to the code they affect. Then it's hard to miss affected comments if one's not doing a shoddy job.

tome 8y ago
I've done it frequently myself when I've changed a line that I originally wrote myself in a way that invalidates a comment written directly above.
dllthomas 8y ago
> Key trick is writing comments as close as possible to the code they affect. Then it's hard to miss affected comments if one's not doing a shoddy job. That also helps it show up in a PR so it may be caught in code review. Even so, IME comments get missed enough that over time I can't be as confident as we'd like that they match the code. I think it's also worth calling out that this key trick is not being applied in the recommendation up-thread, which asks for a block comment at the top of the module.

garmaine 8y ago

Reject pull requests that don't update the documentation (and tests).