"Peter N. Lundblad" <peter@famlundblad.se> writes:
> Well...
>
> "For structure types, document each individual member of the structure as
> well as the structure itself."
>
> I think that's a little overkill.
No, I think it really helps. There have been many times where I've
been reviewing a commit and found that lack of structure field
documentation impeded my ability to understand things (in fact, you'll
sometimes see followup commits from me adding the documentation).
Here's an example:
r18506 is a clarification of existing documentation, not an addition
of new documentation, but it still applies here. People sometimes
neglect to document the pool field in a structure, yet it is not
always the case that the objects of that type are allocated in the
pool they hold internally -- sometimes they are, sometimes not.
Without documentation, you have to go looking in the code. In this
case, if you weren't an expert and didn't happen to know that
svn_fs_new() is the one and only place where svn_fs_t objects are
created, then you might spend considerable effort verifying the
relationship between pool lifetime and object lifetime. And it would
actually matter if, say we ever add UUID caching (as discussed in
r18462 / r18482).
r18506 itself isn't really so important here. I think the previous
text was unambiguous about lifetime too, it just wasn't quite as
direct. But imagine if that pool field hadn't been documented at all.
That would have been bad. Not disastrous, not tragic... but somewhat
inconvenient for non-expert readers of the code.
-Karl
--
www.collab.net <> CollabNet | Distributed Development On Demand
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Fri Feb 17 21:09:47 2006