3 ms·
That's documentation, not comments. Nothing hurts code readability more than huge chunks of markup (markup!) getting in the way of the code you need to read to
by ajross 18y ago
That's documentation, not comments. Nothing hurts code readability more than huge chunks of markup (markup!) getting in the way of the code you need to read to maintain. Javadocxygenwhatever generates pretty web pages, but leads to write-only source files.
- nradov 18y agoI appreciate the readability problem, but what would you propose as an alternative? In my experience, combining the code and documentation in a single file makes it much more likely that developers actually will update the documentation. Besides, any decent editor will hide the documentation if you don't want to see it.
- ajross 18y agoHow about abstraction? Draw a clean line between the API you're trying to document and the code that implements it, and make sure that comments for either don't cross-pollute. This is a good idea anyway. I can't tell you how many automatically generated documentation trees I've seen that are utterly worthless. Documentation of public interfaces gets mixed in with usage notes on internal structures, and you don't know what you're supposed to use.