Hi, On Wed, Nov 04, 2009 at 07:08:45PM +0200, Sergiu Ivanov wrote: > On Fri, Oct 30, 2009 at 10:13:09AM +0100, olafbuddenha...@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-
