ensuring docstrings in new code
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.