Re: [PATCH 3/3] Add the mountee to the list of merged filesystems.

[olafBuddenhagen]

Hi,

On Wed, Nov 04, 2009 at 07:08:45PM +0200, Sergiu Ivanov wrote:
> On Fri, Oct 30, 2009 at 10:13:09AM +0100, olafBuddenhagen@gmx.net
> wrote:
> > On Mon, Aug 17, 2009 at 08:55:37PM +0300, Sergiu Ivanov wrote:

> > > I've added the corresponding comment to ulfs_register, but I
> > > didn't add anything to variable or structure declarations, because
> > > I'm not sure whether it would be suitable to describe the
> > > convention in the comment to the declaration of struct ulfs or in
> > > the comment to the declaration of ulfs_chain.
> > 
> > The latter I'd say -- it's not really a property of the ulfs
> > structure itself, but rather a special entry in the list...

Whoops, sorry, I wasn't paying attention :-(

After looking at the patch, it immediately became clear that indeed the
comment belongs in the ulfs structure itself, not the chain -- it
describes a special value of a particular field in the structure, while
the chain only links the structures.

> > > Also, in ulfs.h, both are near the declaration of ulfs_register,
> > > so it seems to me that it's sufficient to describe the convention
> > > in the comment to ulfs_register only.
> > 
> > Perhaps. Though generally, properly documenting data structures is
> > more important than documenting functions... So I'd rather do it the
> > other way round :-)
> 
> Hm, I didn't know this convention; I'll keep it in mind.

"Show me your code and conceal your data structures, and I shall
continue to be mystified. Show me your data structures, and I won't
usually need your code; it'll be obvious." -- Eric Raymond, paraphrasing
Fred Brooks

> I have eventually commented both the data structures and the
> functions, which, I hope, is not a problem :-)

Only in the sense that more redundancy means more things to update if
something should change there... But I'm not too worried about that :-)

-antrik-