[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: property code cleanup

From: Karl Fogel <kfogel_at_newton.ch.collab.net>
Date: 2001-11-06 21:16:56 CET

Kevin Pilch-Bisson <kevin@pilch-bisson.net> writes:
> On Tue, Nov 06, 2001 at 12:02:38PM -0600, Karl Fogel wrote:
> > Having returned values be dependent on cwd is very rare in Subversion.
> > The more usual behavior is like I described, or even better: the paths
> > should just include TARGET as prefix. That way, everything behaves
> > quite intuitively: for example, you ask for prop X on file F, and you
> > get back a hash with key F and some value.
>
> That is indeed what happens, just (obviously) can't think of an appropriate
> way to say that in a docstring.

May I pontificate some more? A general principle:

  It doesn't matter how awkward the doc string gets, it *must* be
  precise. Readable but ambiguous prose is okay for humans, but not
  for programmers. :-)

That's not to say that style is unimportant -- if you can say it well,
by all means do so. But if not, you _still_ have to say it, even if
awkwardly. The most important thing is not to leave people guessing.

-K

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sat Oct 21 14:36:48 2006

This is an archived mail posted to the Subversion Dev mailing list.