Re: Documentation (was Re: PIL 4 Just Arrived!!!)

[Tim Hill <drtimhill@...>]

> What I have been doing more and more, though, is to write the
> documentation as a document on its own concurrently with but
> slightly in advance of the code. I.e. the documentation shows
> the code as it ought to be, not as it is. Only a cynic can argue
> with that :-)

I have to confess I’m not a great fan of inline documentation, for two reasons. First (and let’s be honest here), developers often are not good at writing good documentation. Second, in our work, where source code is truly locked down, separation of document files and source files is necessary to allow late changes to documents after code lock-down.

Having said that, we take great care to structure our source tree so that source code and it’s associated document files live in close proximity.

—Tim