[Numpy-discussion] ensuring docstrings in new code

[Joe Harrington]

Over on [Numpy-discussion] Extending documentation to c code, David
G. gave voice to a frustration he and I share about the status of
documentation in the new-code development process.  I don't want to
paint with a broad brush, yet in recent months there have been a
number of checkins, unanimously passed off by the entire core
development group/Steering Committee, without a single mention that
this code entered SVN with deficient or even completely absent
docstrings.  I'm not pointing out the offenses simply because I don't
think public embarrassment is a good policy, but David has a list that
we can share with developers privately.

It is really hard to do much without docs on anything you didn't write
yourself.  When I learned how to program, it was beaten into me to
document as I went along, that good projects always did, and that
major problems up to and including a complete implosion and
abandonment of the software could and sometimes did result if docs
were not kept current.

The Doc Project is not the writing arm of the developers.  So far, we
have only worked on the existing software, not anything new, and most
of us don't even have SVN access.  Rather, the Doc Project is cleaning
up what others, in their haste, did not do, and it frustrates us to
see others still not doing it.

What change of procedures would ensure that no code, possibly
including bug fixes, enters SVN without a ready-for-review docstring?

Perhaps new code could be reviewed according to a checklist that
includes "has a ready-for-review docstring".  Or perhaps announcements
to the lists of pending code checkins should include [CHECKIN] in the
subject, to attract the attention of the Doc Project's Editor (i.e.,
David), so that he can act as an outside cop.  Or maybe the SVN can
somehow be made to check for docstrings, or to ask for them on
checkin.  Or maybe something in the build could make such a list and
compare it to the last list and complain if there are new routines on
it.  We've called for a rule of no new code without docs many times.
I'm not sure of the best solution, but we need something or things
won't change.

It's not like these are hard to write.  The lack of a ready-for-review
docstring is a major bug in itself.

--jh--