Re: [PATCH 1/7] Softrefs: Add softrefs header file with API documentation

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Jun 10, 2007, 06:58 UTC
Message-ID: <Pine.LNX.4.64.0706100750440.4059@racer.site>
In-Reply-To: <200706092021.43314.johan@herland.net>

Hi,

On Sat, 9 Jun 2007, Johan Herland wrote:

> See patch for documentation.

This is preposterous. Either you substitute the patch for a documentation, or you document it in the commit message. I consider commit messages like "See patch for documentation" as reasonable as all those CVS "** no message **" abominations.

Show 10 quoted lines

> + * The softrefs db consists of two files: .git/softrefs.unsorted and
> + * .git/softrefs.sorted. Both files use the same format; one softref per line
> + * of the form "<from-sha1> <to-sha1>\n". Each sha1 sum is 40 bytes long; this
> + * makes each entry exactly 82 bytes long (including the space between the sha1 + * sums and the terminating linefeed).
> + *
> + * The entries in .git/softrefs.sorted are sorted on <from-sha1>, in order to
> + * make lookup fast.
> + *
> + * The entries in .git/softrefs.unsorted are _not_ sorted. This is to make
> + * insertion fast.

This sure sounds like you buy the disadvantages of both. Last time I checked, it was recommended to look at your needs and pick _one_ appropriate data structure fitting _all_ your needs.

Besides, your lines are way too long. Yes, it is not in Documentation/SubmittingPatches, but even just a cursory look into the existing source shows you that it is mostly 80-chars-per-line. I think it goes without saying that you should try to imitate the existing practices in any project, and since you have to read the source to get acquainted with it _anyway_, it would only be a duplication to have it in SubmittingPatches, too.

Ciao, Dscho