[Sheepdog] [PATCH v4 03/12] farm: add sha1_file operations

[Christoph Hellwig]

On Wed, Dec 28, 2011 at 09:50:53PM +0800, Liu Yuan wrote:
> > why?
> 
> 
> Compression is supposed to reduce the storage usage for snapshot
> objects. And I assume hashing the compressed content is faster than the
> original one.
> 
> If not, any benefits?

I'm just wondering.  In general a rationale like that should go into
the commit message.  Preferably including numbers validating the choice.

> >> - the general consistency of an object can always be tested independently
> >>   of the contents or the type of the object: all objects can be validated
> >>   by verifying that
> >> 	(a) their hashes match the content of the file and
> >>   	(b) the object successfully inflates to a stream of bytes that
> >>   	forms a sequence of <sha1_file_hdr>  + <binary object data>
> > 
> > These comments should not only be in the commit message but also in
> > the source code.
> > 
> 
> 
> I have written it in doc/farm-internals.txt, and it looks a little bit
> redundant to include them in the files, isn't it?

People generally look at the file for documentation first.  Having a few
paragraphs describing the concepts in the file or for the individual
exported functions makes reading the code a lot easier.