— Uncle Bob in "Clean Code"
I don't care about the code!
what happens when I use it?
am I supposed to check?
what if I have to implement an interface?
I care about the code!
I have to change it!
what about lesser known ones?
I care even less about the tests!
Test coverage better be > 90%!
A common fallacy is to assume developers incapable to express themselves lucidly and clearly in a natural language will somehow be able to write lucid and clean code.
So? Do we get rid of them?
compared to writing code and tests.
⇝ Comments and code must be close!
The core to modularizing any non-trivial problem!
Comments can help with both!
the right level of abstraction.
Context is invaluable when revisiting code!
Comments can be 2nd line of defense.
It's funny how writing documentation can spur redesign: it's easier to simplify a complex API than try to document it completely.
…​maybe the code needs to be improved.
You become your own reviewer!
It is hard to update far-away comments!
But not all work for every use case.
very high, need to be absolutely up to date!
Usually JavaDoc on classes and methods.
at the beginning of a class/method.
* whitish colors as favorites.
* For details see issue #1534.
// but too scared to delete.
We're working with unfeeling material.
Comments are a tool to facilitate understanding. We should use it wisely!
Write clean code and good tests.
use phrases like "at the time of writing"
What's impacted when you change code?
Check comments on those elements!