5 ms·

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, yo

by 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?
- jwilliams 13y ago
  "The coder" probably should spend time talking to customers, testing designs, interacting with their peers, reading other code, learning. None of these contribute directly to achieving a theoretical maximum output of SLoC. If that's you're metric, I don't think it's a good one. Aside from niche projects - A great deal of time goes into realising software. The incremental cost of comments is minuscule. I have lots of challenges and bottlenecks. The time to type comments isn't one of them.
  - maratd 13y ago
    > a theoretical maximum output of SLoC. If that's you're metric, I don't think it's a good one. That's certainly not my metric and I definitely don't believe it's a good one. My metric is readability. The ability to return to a piece of code 6 months down the road and be able to understand precisely what's happening. > I have lots of challenges and bottlenecks. The time to type comments isn't one of them. Oh, I know. It's very easy to add a comment that you think will help clarify things down the road, but instead, ends up being more cryptic than your code. By definition, a comment is something short and half-thought out. It's a comment. As I said in the post up above, stay away from comments. If you have to annotate, write documentation instead.
    - WayneDB 13y ago
      That's not the definition of the word "comment" at all. Who is the authority on whether commentless code is good or not? Could this possibly be completely subjective? Hmmm. > Oh, I know. It's very easy to add a comment...but [it] ends up being more cryptic than your code. You don't know that :)

by WayneDB 13y ago

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?

jwilliams 13y ago
"The coder" probably should spend time talking to customers, testing designs, interacting with their peers, reading other code, learning. None of these contribute directly to achieving a theoretical maximum output of SLoC. If that's you're metric, I don't think it's a good one. Aside from niche projects - A great deal of time goes into realising software. The incremental cost of comments is minuscule. I have lots of challenges and bottlenecks. The time to type comments isn't one of them.
- maratd 13y ago
  > a theoretical maximum output of SLoC. If that's you're metric, I don't think it's a good one. That's certainly not my metric and I definitely don't believe it's a good one. My metric is readability. The ability to return to a piece of code 6 months down the road and be able to understand precisely what's happening. > I have lots of challenges and bottlenecks. The time to type comments isn't one of them. Oh, I know. It's very easy to add a comment that you think will help clarify things down the road, but instead, ends up being more cryptic than your code. By definition, a comment is something short and half-thought out. It's a comment. As I said in the post up above, stay away from comments. If you have to annotate, write documentation instead.
  - WayneDB 13y ago
    That's not the definition of the word "comment" at all. Who is the authority on whether commentless code is good or not? Could this possibly be completely subjective? Hmmm. > Oh, I know. It's very easy to add a comment...but [it] ends up being more cryptic than your code. You don't know that :)