From: Paul Mackerras <paulus@samba.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Message-ID: <15816.23157.790358.720568@argo.ozlabs.ibm.com>
Date: Wed, 6 Nov 2002 10:55:33 +1100
To: linux-kernel@vger.kernel.org
Cc: davidm@snapgear.com
Subject: [RANT] Totally inadequate commenting in flat.h
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 1212
Lines: 38

Looking over the recent changes in Linus' tree, I saw there was this
new file, include/linux/flat.h.  Hmmm, uninformative name, what's this
file about?  I look in the file and here is how it starts:

/* Copyright (C) 1998  Kenneth Albanowski <kjahds@kjahds.com>
 *                     The Silver Hammer Group, Ltd.
 * Copyright (C) 2002  David McCullough <davidm@snapgear.com>
 */

#ifndef _LINUX_FLAT_H
#define _LINUX_FLAT_H

#define	FLAT_VERSION			0x00000004L

/*
 * To make everything easier to port and manage cross platform
 * development,  all fields are in network byte order.
 */

struct flat_hdr {
	char magic[4];
	unsigned long rev;          /* version (as above) */

etc.

*Completely* uninformative.  How is anyone supposed to know what this
relates to?  Is it something to do with a network device, or a
filesystem, or an executable format, or what?

[And no, don't reply to this telling me what it's about, add some
comments to the file instead.]

Paul.
-
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/