5 ms·

"My code is so good it doesn't need comments" is usually untrue. Don't fall for it. If you can name an API or framework that you use that has near-zero comment

"My code is so good it doesn't need comments" is usually untrue. Don't fall for it. If you can name an API or framework that you use that has near-zero comments... And benefits from that, I'd like to know. I can name plenty that are a pleasure to use because of clear, replete documentation. If you're thinking your code is different from an API, you're right - it's worse. An API is designed for consumption, whereas your code is buried. It might not get look at by another human for months... or years. Who will be looking at that piece of code next? You? Ok. Be your own worst enemy. More than likely it's someone else looking. And why? Maybe because it doesn't work like it should, or conditions have changed, or it needs to be extended. Bad documentation can be just as bad as bad code, but "don't comment your code" is a road to madness.

foobarbazqux 13y ago
"My comments are so good they don't need code" is usually untrue too...
- talmand 13y ago
  No, it's untrue all the time because it doesn't make any sense.
  - foobarbazqux 13y ago
    Surely it depends on what your program is trying to not do.
    - ErrantX 13y ago
      My favourite piece of code that used to be in our code base was a set of empty PHP files with the comment "this file intentionally left blank". Created so that the core framework could be unit tested. (This was before I came on board and introduced the idea of filesystem mocking).
      - NoodleIncident 13y ago
        See also Word press's "Silence is golden" php files.
maratd 13y ago
> "My code is so good it doesn't need comments" is usually untrue. I still don't see this as a convincing argument. Our greatest constraint is time. So the question becomes do I spend my time writing comments or do I re-factor the code I wrote to make it more readable? I always opt for re-factoring my code. Have you read some of the comments most developers leave? They either explain the most obvious inane functionality or use it as their personal todo list. And sometimes they do both. That is not helpful. In instances where I know my code will be a critical component which will be utilized by many others, I opt to write documentation rather than comments. And there is, of course, a difference. Comments are inline, documentation is frequently split out. Comments are frequently inane explaining the obvious, while documentation goes in-depth into not only how the code works, but what it is trying to accomplish and why. Documentation also provides examples of use, which is far more useful than anything else. When I reach for the documentation option, I almost always include a separate markdown file with the same name as the original file. There are then a ton of options in terms of software that aggregate those files into a searchable, indexed collection. Focus on code quality and if some sort of annotation is necessary, write documentation, but don't leave comments.
- WayneDB 13y ago
  Inline documentation done right is undeniably a massive time-saver though because you don't need to search a separate document at all. With the right editor, your documentation can also be folded into a single line or be hidden altogether. Can you show us any concrete examples of high quality, comment-less codebases? The last (mostly) comment-less source that I read through last year was Node.js and I wouldn't exactly call that high quality or well documented.
  - maratd 13y ago
    > Can you show us any concrete examples of high quality, comment-less codebases? No. Quite simply, there is a collective perception that if a codebase lacks inline comments, it's of poor quality. Very few would dare to publish such a work. I have a different challenge for you. Take a high quality codebase and delete all the inline comments. You'll find it's just as readable, if not more so. How much better would it have been if the coder had spent the time writing better code rather than adding superfluous comments?

foobarbazqux 13y ago

"My comments are so good they don't need code" is usually untrue too...

talmand 13y ago
No, it's untrue all the time because it doesn't make any sense.
- foobarbazqux 13y ago
  Surely it depends on what your program is trying to not do.
  - ErrantX 13y ago
    My favourite piece of code that used to be in our code base was a set of empty PHP files with the comment "this file intentionally left blank". Created so that the core framework could be unit tested. (This was before I came on board and introduced the idea of filesystem mocking).
    - NoodleIncident 13y ago
      See also Word press's "Silence is golden" php files.

maratd 13y ago

> "My code is so good it doesn't need comments" is usually untrue. I still don't see this as a convincing argument. Our greatest constraint is time. So the question becomes do I spend my time writing comments or do I re-factor the code I wrote to make it more readable? I always opt for re-factoring my code. Have you read some of the comments most developers leave? They either explain the most obvious inane functionality or use it as their personal todo list. And sometimes they do both. That is not helpful. In instances where I know my code will be a critical component which will be utilized by many others, I opt to write documentation rather than comments. And there is, of course, a difference. Comments are inline, documentation is frequently split out. Comments are frequently inane explaining the obvious, while documentation goes in-depth into not only how the code works, but what it is trying to accomplish and why. Documentation also provides examples of use, which is far more useful than anything else. When I reach for the documentation option, I almost always include a separate markdown file with the same name as the original file. There are then a ton of options in terms of software that aggregate those files into a searchable, indexed collection. Focus on code quality and if some sort of annotation is necessary, write documentation, but don't leave comments.

WayneDB 13y ago
Inline documentation done right is undeniably a massive time-saver though because you don't need to search a separate document at all. With the right editor, your documentation can also be folded into a single line or be hidden altogether. Can you show us any concrete examples of high quality, comment-less codebases? The last (mostly) comment-less source that I read through last year was Node.js and I wouldn't exactly call that high quality or well documented.
- maratd 13y ago
  > Can you show us any concrete examples of high quality, comment-less codebases? No. Quite simply, there is a collective perception that if a codebase lacks inline comments, it's of poor quality. Very few would dare to publish such a work. I have a different challenge for you. Take a high quality codebase and delete all the inline comments. You'll find it's just as readable, if not more so. How much better would it have been if the coder had spent the time writing better code rather than adding superfluous comments?