[RANT] Totally inadequate commenting in flat.h

From: Paul Mackerras (paulus@samba.org)
Date: Tue Nov 05 2002 - 18:55:33 EST


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/



This archive was generated by hypermail 2b29 : Thu Nov 07 2002 - 22:00:40 EST