|
|
|
|
|
|
by denton-scratch
1614 days ago
|
|
|
Agree. I suspect the difference of opinion might be down to systems like Javadoc, that transform code comments into API docs. But Javadoc comments are often auto-generated from function prototypes, which results in Javadoc comments that add nothing to the raw code except bloat. I don't think I'ver ever seen good documentation produced from doc-comments. There's another thread on the front page about literate programming; I suspect that doc-comments amount to an effort to weave code and documentation together, in a knuthian manner, to kind-of automate literate programming. It doesn't work, AFAICS. You get bloated code and bad docs. |
|
|
doc-comments are good because it explains well what the class/method/whatever are there for, sometimes with examples, that helps understand the code.
But I hate that they use so much space inside the source code that I have to scroll hundreds of lines to read the code. And those doc-comments are filled with markup that makes it harder to read.
I would like a literate a system that generates source code that is well formatted and where the only comments are what the function does and some inner function comment where the code is complex. Every other lengthy and detailed description should be inside the produced pdf/html.