This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
Joe Buck wrote:
OK, the *best* would be written by that almost non-existent programmer who
combines a love of writing clear English prose with the extraordinary
discipline required to do it first and keep it current. But since this
species is almost non-existent, you need to read my phrase "best
documentation" for "best documentation achievable in practice".
You are FAR too pessimistic, I know lots of programmers who meet
these criteria. It is of course important that comments are reviewed
with the same energy and intensity used in reviewing code. You simply
have to establish an environment in which comments are first class
citizens and everyone spends effort appropriately
In any case, we have to go from what we have: right now we have code that
is not adequately documented. Time travel is not an option.
Sure, but we can in many cases ask authors to do the best retrospective
job they can (and preferably not simply tell us to go rummage around in
the code :-)