Hacker News Reader

Comment by ChrisMarshallNY | Hacker News Reader

I’d guess that tools like Doxygen and Apple docc are probably the most obvious examples of documentation extraction.

I’ve written code for many years, with Doxygen/Jazzy/docc in mind (still do[0]). I feel that it’s a big help.

[0] https://littlegreenviper.com/leaving-a-legacy/

Documentation like doxygens is almost completely opposite from literate programming. The comment you are responding to emphasizes the ability to determine yourself the order in which to present the documentation. Literate programming is writing a document in the first place where, as an afterthought, a program can be extracted. Source code with doxygen is source code where, as an afterthought, documention can be extracted from. In many cases doxygen documention is quite worthless. Very often it is very helpfully documented that the method get_height, "gets the height". It is very fragmentary documentation where the big picture is completely missing. There is also a case where doxygen-like documentation is needed. This is when writing a library that is going to be used by many people. But then the doxygen comments should only be used on methods that you want those other people to use. And then there is still the danger that there will be too little higher level documentation because the doxygen is treated like it is sufficient.

Literate programming is, in my opinion, only used very seldomly because keeping an accurate big picture view of a program up to date is a lot of work. It fits with a waterfall development process where everything that the program is supposed to do is known beforehand. It fits well with education. I think it is no coincidence that it was brought to prominence by D.E. Knuth who is also very famous as an educator.

OK. Fair enough, but remember that Doxygen also analyzes code structure, and can generate things like UML diagrams, and inheritance trees.

Maybe a tool like Rational Rose is more along those lines.

I’ve always been a proponent of writing code in a manner that affords analysis, later. That’s usually more than just adding headerdoc.

Reply on news.ycombinator.com