4 ms·

I have heard the inline comment complaint first hand, especially as it relates to documentation of library headers. The biggest issues come from long-form comme

I have heard the inline comment complaint first hand, especially as it relates to documentation of library headers. The biggest issues come from long-form commentary between every API that add more noise than signal to a header file. To be sure, inline commentary of any kind is better than none at all! However, an inflection point exists where the source file is a poor medium for exhaustive documentation meant for human consumption. As an open source library maintainer, too, I have found this style of documentation problematic to maintain. Brief comments that should be digested nearly every time an API is referenced (e.g., because there is a funky precondition or some other gotcha a user should be aware of) are certainly useful, and comments within the implementations of routines are good to have. In general, code should speak for itself, and any associated comments should fill in gaps where the code's intent is not obvious. Such code commentary is not the problem hyde is looking to solve.

jlg23 8y ago
Not sure where we disagree: Bad documentation is bad. Yes. But what is specific about inline comments per se?
- MontagFTB 8y ago
  I think we agree far more than otherwise. Where we might disagree is with my claim that good, long-form documentation of sources/headers/APIs is better done out-of-line.
  - jlg23 8y ago
    Fair enough, I never said anything about "long form documentation" ;)
kevin_thibedeau 8y ago
Don't load header files with documentation comments. Put them in the implementation. I don't see where the trouble is in properly documenting your code within the code. That isn't any where near as intrusive as literate programming. On an active code base nobody is going to keep external docs up to date without a taskmaster to force the issue. Open source code bases are often a poor example of good coding practices. 1000's of lines can go by with nary a comment. Everybody's so leet they don't need them? That's great if you are the principal author and know (or knew) what everything did at one time. Not so great in a commercial setting with a fluid developer base where the noobs need to know what's going on without reading every piece of code.
- jcelerier 8y ago
  > Don't load header files with documentation comments. Put them in the implementation. no, that's terrible. How do you do when you don't want to install the source of every lib you use ?
  - kevin_thibedeau 8y ago
    You read the generated docs or get the source.

jlg23 8y ago

Not sure where we disagree: Bad documentation is bad. Yes. But what is specific about inline comments per se?

MontagFTB 8y ago
I think we agree far more than otherwise. Where we might disagree is with my claim that good, long-form documentation of sources/headers/APIs is better done out-of-line.
- jlg23 8y ago
  Fair enough, I never said anything about "long form documentation" ;)

kevin_thibedeau 8y ago

Don't load header files with documentation comments. Put them in the implementation. I don't see where the trouble is in properly documenting your code within the code. That isn't any where near as intrusive as literate programming. On an active code base nobody is going to keep external docs up to date without a taskmaster to force the issue. Open source code bases are often a poor example of good coding practices. 1000's of lines can go by with nary a comment. Everybody's so leet they don't need them? That's great if you are the principal author and know (or knew) what everything did at one time. Not so great in a commercial setting with a fluid developer base where the noobs need to know what's going on without reading every piece of code.

jcelerier 8y ago
> Don't load header files with documentation comments. Put them in the implementation. no, that's terrible. How do you do when you don't want to install the source of every lib you use ?
- kevin_thibedeau 8y ago
  You read the generated docs or get the source.