3 ms·

"It is well known that I prefer code that has few comments. I code by the principle that good code does not require many comments. Indeed, I have often suggeste

"It is well known that I prefer code that has few comments. I code by the principle that good code does not require many comments. Indeed, I have often suggested that every comment represents a failure to make the code self explanatory. I have advised programmers to consider comments as a last resort." https://blog.cleancoder.com/uncle-bob/2017/02/23/NecessaryComments.html https://blog.cleancoder.com/uncle-bob/2017/02/23/NecessaryCo... I tend to prefer no comments, but more descriptive methods. There may be occasional exceptions.

blowski 8y ago
Also, the post encourages comments saying “TODO”. I’ve yet to see a codebase where that helps anything.
- gizmo686 8y ago
  I've seen them be useful when used in combination with a bug tracker. That way is investigating the same problem they are likely to find out that it has already been reported. And having a todo mark a specific region of code can save time when we jump in to fix it. I have also had situations where we decided "we are releasing in a month, cut corners and we'll deal with it later", and putting in TODOs greatly help deal with it later
- kstenerud 8y ago
  I use TODO often in my code. It's how I mark things as incomplete but not forgotten, which means that the code should not go into production until the TODOs are handled.
blotter_paper 8y ago
>There may be occasional exceptions. I feel like comments belong in wrappers for unintuitive interfaces when a judgement call has been made to not replace those interfaces in-house due to project constraints. That's about it.
dictum 8y ago
> I have often suggested that every comment represents a failure to make the code self explanatory. Part of why Worse Is Better is that relying on self-discipline and a healthy environment is a risky bet. When code comments are presented as a failure to self-document, they are simply not written, irrespective of the actual clarity of the code. Add some pressure or toxic environment and everyone who's not able to grok your codebase won't complain about it — it is self-documenting! If you don't get it, the problem is on your end.
Roboprog 8y ago
I wish the arrogant meme plague of “self documenting “ code would just die, already. TODO: get the link for the study showing it’s about 10% faster to read code with module level documentation
theamk 8y ago
Some classes of comments are pretty had to replace with self-explanatory code: historical, design decisions and negative things. // This code uses FOO because when it was originally written, we expected to process millions of items, so fast random access time was important. This is no longer the case -- feel free to refactor to use BAR instead. // Do not refactor this code to use BAR! While this will make the function shorter, the result will have O(n^3) complexity, and this function may get millions of input items in some cases.

blowski 8y ago

Also, the post encourages comments saying “TODO”. I’ve yet to see a codebase where that helps anything.

gizmo686 8y ago
I've seen them be useful when used in combination with a bug tracker. That way is investigating the same problem they are likely to find out that it has already been reported. And having a todo mark a specific region of code can save time when we jump in to fix it. I have also had situations where we decided "we are releasing in a month, cut corners and we'll deal with it later", and putting in TODOs greatly help deal with it later
kstenerud 8y ago
I use TODO often in my code. It's how I mark things as incomplete but not forgotten, which means that the code should not go into production until the TODOs are handled.

blotter_paper 8y ago

>There may be occasional exceptions. I feel like comments belong in wrappers for unintuitive interfaces when a judgement call has been made to not replace those interfaces in-house due to project constraints. That's about it.

dictum 8y ago

> I have often suggested that every comment represents a failure to make the code self explanatory. Part of why Worse Is Better is that relying on self-discipline and a healthy environment is a risky bet. When code comments are presented as a failure to self-document, they are simply not written, irrespective of the actual clarity of the code. Add some pressure or toxic environment and everyone who's not able to grok your codebase won't complain about it — it is self-documenting! If you don't get it, the problem is on your end.

Roboprog 8y ago

I wish the arrogant meme plague of “self documenting “ code would just die, already. TODO: get the link for the study showing it’s about 10% faster to read code with module level documentation

theamk 8y ago

Some classes of comments are pretty had to replace with self-explanatory code: historical, design decisions and negative things. // This code uses FOO because when it was originally written, we expected to process millions of items, so fast random access time was important. This is no longer the case -- feel free to refactor to use BAR instead. // Do not refactor this code to use BAR! While this will make the function shorter, the result will have O(n^3) complexity, and this function may get millions of input items in some cases.