docstrings discussion

[John Arbash Meinel]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Ian Clatworthy wrote:
> Aaron Bentley wrote:
> 
>> I think this should address all your comments.  I have added scads of
>> docstrings despite philosophical objections that it violates DRY, so
>> that it can get merged separately from the discussion of how much
>> documentation is appropriate.
> 
> Aaron,
> 
> Thanks for the additional documentation. I forgot to reply to the
> concerns you raised ...
> 
> To be clear, I agree that adding docstrings for the sake of it isn't
> wise. I'd go further and say that wrong docstrings can be worse than no
> docstrings. I also agree that your code does a great job of being clear
> and is largely self-documenting. We all ought to be aiming for that. On
> all of these points, I suspect we're in agreement.
> 
> My request for docstrings had nothing to do with helping programmers who
> were viewing and/or editing the bzrlib code in vim/Emacs/whatever. It
> was to do with *other* mediums for browsing the API, e.g. webpages
> generated by pydoctor. Increasingly as well, smart IDEs can popup the
> docstrings for API calls in balloon help. It sounds corny but it's
> really useful for many developers in my experience.
> 
> Of course, many of us use vim and are working on the bzrlib code itself
> so docstrings can be more trouble than value. In the medium term though,
> the typical bzrlib API programmer is more likely to be treating it as a
> blackbox, more like how most of us treat the standard Python library.
> Catering for webpage generation tools and IDEs by writing good
> docstrings is therefore something I think we need to be conscious of IMO
> (without going crazy about it).
> 
> My 2c,
> Ian C.


I still prefer having docstrings that at least define the parameters. I
know Aaron feels his code is self documenting. And it is when he wrote
it. But often it takes me a considerable about of digging through the
code to see exactly how "foo" is being used, to be able to determine
that it should actually be a Revision object (and not a revision_id
string, or a RevisionTree, or a ('revision_id', Tree) tuple, etc).

Also, code tends to document the "how" or "what" is going on, but not
the "why", which is what we should try to put into the docstrings.

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFG9BSqJdeBCYSNAAMRArEBAKCqDW2ntvGInSRmlVsQePTrop4SIQCeNdyf
ZHFLK35BxBwQs7o42WiiY4M=
=q73a
-----END PGP SIGNATURE-----