Re: [PATCH 1/3] git-branch: add --track and --no-track options

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Mar 5, 2007, 23:09 UTC
Message-ID: <Pine.LNX.4.63.0703052359440.13683@wbgn013.biozentrum.uni-wuerzburg.de>
In-Reply-To: <45EC8959.1090303@lu.unisi.ch>

Hi,

On Mon, 5 Mar 2007, Paolo Bonzini wrote:

Show 9 quoted lines

> > Yes, this is what the source does. But again, the return value is what 
> > you should -- and indeed forever can -- rely on. I am not really happy 
> > that dwim_ref() touches ref, even if nothing was found, but it is an 
> > _implementation detail_.
> 
> It's not fair to not have any documentation in the code, force the 
> contributor to reverse engineer the documentation, and say it is relying 
> on an implementation detail.  In otherwise undocumented code, 
> implementation == interface.

Ah, sorry. The "return 0 on success, other values mean different sorts of errors" concept is so ubiquituous in Unix-like systems, that nobody bothered documenting that.

Actually, we usually use "-1" to mean error, and depending on the function have different meanings for ">0".

But the best documentation for a function is actually the code using it, and I thought that you had a look at them. Very often, I do "git grep bla" to see where the function called "bla()" was used. For me, examples are worth a thousand man pages...

A supplemental remark on the sscanf() thing: when I was forced to work on Windows, I made it a habit not to rely on specs. So often, things just did not work as described, and complaining did not help. For example, we had to throw out _all_ uses of templates in a certain project, because the C compiler would choke with an internal error.

So, my hesitation regarding sscanf() stems mainly from the fact that it appears rarely used to me, and such constructs are more likely to break expectations when trying to port to different architectures.

And _that_ is why I do not hesitate using printf(): it is much more likely that an incompatibility in printf() is fixed, whereas with sscanf() it will likely end up worked-around all the time instead of being fixed.

Ciao, Dscho