4 ms·

W.r.t. "self-documenting" code: at best, clear code tells you what it does. What it's supposed to do and why will always be left to comments. I can't count th

by KMag 6y ago

W.r.t. "self-documenting" code: at best, clear code tells you what it does. What it's supposed to do and why will always be left to comments. I can't count the number of times I've read some code that was very clear that it generally did the correct thing, but clearly wasn't handling some corner case, and it wasn't clear if I had missed something that obviously made the corner case impossible, the author had missed the corner case, or something else was going on.

eXpl0it3r 6y ago
And how should someone write a comment about that they intentionally forgot about some corner-cases? Or if they did add a similar comment and in the meantime someone implemented it, but didn't remove the comments, how many people will only read the comment and not look at the code?
- KMag 6y ago
  If the explanation of intended behavior left out the corner case, then it would be much more likely that the author hadn't considered the corner case. More insight into the author's thought process gives you more confidence in your assessment.
- em-bee 6y ago
  corner-cases should either be mentioned in the comments or be handled in the code. if they are neither, then the author missed them. a future developer potentially forgetting to update a comment is not an excuse to avoid commenting.
- slowmovintarget 6y ago
  In a perfect world... You'd find that in the commit log for the code. Comments aren't the right place for things you forgot to do, or things that occur to you after the code sort of works. The commit message, and unit tests, are where those ideas can be best captured. I tend to point my team at this as a practice: https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/
tikhonj 6y ago
> at best, clear code tells you what it does. This depends a lot on what you mean by "clear" code! You can write higher-level code with abstractions that emphasize the what rather than the how and you can write code that explicitly captures important additional information like invariants. Personally, I've found aiming for that works better than writing code where the "how" is clear at the expense of the "what" so that readers don't lose the forest for the trees. I am not sure I'm explaining the difference well—it would benefit from examples that I am too tired to provide right now—and documentation is still useful even with higher-level code, but my point is that code absolutely can and should clearly reflect many of the things you would also cover in documentation.
- KMag 6y ago
  > but my point is that code absolutely can and should clearly reflect many of the things you would also cover in documentation. I absolutely agree, but my point was very specific about the "what should" and "why". At best, one could infer some intent from invariants, and hopefully the mapping between the invariants and the requirements document is pretty clear, but comments are still better at explicitly referencing requirements documentation and explaining why the chosen solution is preferable to alternatives.

by KMag 6y ago

eXpl0it3r 6y ago

And how should someone write a comment about that they intentionally forgot about some corner-cases? Or if they did add a similar comment and in the meantime someone implemented it, but didn't remove the comments, how many people will only read the comment and not look at the code?

KMag 6y ago
If the explanation of intended behavior left out the corner case, then it would be much more likely that the author hadn't considered the corner case. More insight into the author's thought process gives you more confidence in your assessment.
em-bee 6y ago
corner-cases should either be mentioned in the comments or be handled in the code. if they are neither, then the author missed them. a future developer potentially forgetting to update a comment is not an excuse to avoid commenting.
slowmovintarget 6y ago
In a perfect world... You'd find that in the commit log for the code. Comments aren't the right place for things you forgot to do, or things that occur to you after the code sort of works. The commit message, and unit tests, are where those ideas can be best captured. I tend to point my team at this as a practice: https://chris.beams.io/posts/git-commit/ https://chris.beams.io/posts/git-commit/

tikhonj 6y ago

> at best, clear code tells you what it does. This depends a lot on what you mean by "clear" code! You can write higher-level code with abstractions that emphasize the what rather than the how and you can write code that explicitly captures important additional information like invariants. Personally, I've found aiming for that works better than writing code where the "how" is clear at the expense of the "what" so that readers don't lose the forest for the trees. I am not sure I'm explaining the difference well—it would benefit from examples that I am too tired to provide right now—and documentation is still useful even with higher-level code, but my point is that code absolutely can and should clearly reflect many of the things you would also cover in documentation.

KMag 6y ago
> but my point is that code absolutely can and should clearly reflect many of the things you would also cover in documentation. I absolutely agree, but my point was very specific about the "what should" and "why". At best, one could infer some intent from invariants, and hopefully the mapping between the invariants and the requirements document is pretty clear, but comments are still better at explicitly referencing requirements documentation and explaining why the chosen solution is preferable to alternatives.