Date: Thu, 10 Aug 2006 02:48:16 -0700
From: Andrew Morton <akpm@osdl.org>
To: Alex Tomas <alex@clusterfs.com>
Cc: cmm@us.ibm.com, linux-fsdevel@vger.kernel.org,
       ext2-devel@lists.sourceforge.net, linux-kernel@vger.kernel.org
Subject: Re: [Ext2-devel] [PATCH 1/9] extents for ext4
Message-Id: <20060810024816.9d83c944.akpm@osdl.org>
In-Reply-To: <m37j1hlyzv.fsf@bzzz.home.net>
References: <1155172827.3161.80.camel@localhost.localdomain>
	<20060809233940.50162afb.akpm@osdl.org>
	<m37j1hlyzv.fsf@bzzz.home.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 1125
Lines: 26

On Thu, 10 Aug 2006 13:29:56 +0400
Alex Tomas <alex@clusterfs.com> wrote:

>  AM> - The code is very poorly commented.  I'd want to spend a lot of time
>  AM>   reviewing this implementation, but not in its present state.  
> 
> what sort of comments are you expecting?

Ones which tell me what the code is attempting to do.  Ones which tell me
the things which I need to know and which I cannot determine from the
implementation within a reasonable period of time.  Ones which tell me
about the hidden design decisions, the known shortcomings, the
things-still-to-do.

It's a bit of an artform, really.  I guess one needs to put oneself in the
position of the reader, then work out what the reader wants to know.

Good examples don't immediately leap to mind, I'm afraid.  Maybe some of
fs/buffer.c?  That's important and pretty tricky code in there, so it goes
to some lengths.

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/