5 ms·
> Secondly (and ironically), experienced users of these libraries eventually find inline documentation to be more of a distraction than a help, cluttering code
by jlg23 8y ago
> Secondly (and ironically), experienced users of these libraries eventually find inline documentation to be more of a distraction than a help, cluttering code with comments they no longer read.
Do they? In 20+ years of professional software development I have not once heard this. I heard lots of criticism about bad documentation of the style
// Increment i by 1
i++;
but never ever fundamental criticism of inline comments except from the literal programming community (I think they have a point there, but their baseline is considerably higher).
Edit: Using clang is a very good choice, imho. If I was coding in c++, I'd probably use the tool just for that alone.
- MontagFTB 8y agoI 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 agoNot sure where we disagree: Bad documentation is bad. Yes. But what is specific about inline comments per se?
- kevin_thibedeau 8y agoDon'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 agoYou read the generated docs or get the source.