docstrings discussion

[Aaron Bentley]

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

John Arbash Meinel wrote:
> I still prefer having docstrings that at least define the parameters.

I think that as a rule, it's pointlessly redundant.  If a variable is
named "is_present", I am going to assume that's a bool.  I'm going to
assume "filename" is a basestring that represents a filename.

As a guideline, it's fine, but there are a lot of exceptions.

> I
> know Aaron feels his code is self documenting.

That's stretching it a bit.  I think *some* of my code is
self-documenting.  In many other cases, I go to great lengths to
document it, because I know it's not obvious.

Documenting the obvious is not only pointless, it's counterproductive.
Because if there's documentation, then I assume it's not self
documenting, and I can't use the signature alone to understand it.  So I
read the docs.  And if the code *is* self-documenting, that's a waste of
time.

> 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).

Look, everyone has different thresholds for obvious/inobvious.  The most
thorough documentation would be pseudocode that looked exactly like the
implementation.  The other extreme is also less than helpful.

I don't think that Reconfigure.to_branch is really very hard to grasp.
Likewise Reconfigure.apply.

But I did document Reconfigure.planned_changes, because I thought maybe
it might be unclear.

> 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.

The "why" in code-level documentation should be pretty limited, e.g.
"Delete the file before moving a new on in place, because win32 doesn't
support atomic rename".

Higher level documentation should describe "why" you would call
"Branch.open_containing" vs "Branch.open" vs BzrDir.open_containing.

e.g. http://bazaar-vcs.org/Integrating_with_Bazaar

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

iD8DBQFG9DqO0F+nu1YWqI0RAmmIAJ41EiFmPW+hOxdoR95I2ae68K/+xACeK3FW
T7MPMgF1r0n0do6goGwUihs=
=U84W
-----END PGP SIGNATURE-----