Messages in this thread Patch in this message | | | Date | Wed, 6 Nov 2002 10:59:41 +1000 | From | David McCullough <> | Subject | Re: [RANT] Totally inadequate commenting in flat.h |
| |
Hi Paul,
Fair comment, however, have you looked at a lot of the other files in include/linux ? Plenty of examples with the same lack of comments, a good one that does essentially the same thing as flat.h:
include/linux/elf.h
No excuses though, here's a patch to add a comment about what the file is used for,
Cheers, Davidm
Index: include/linux/flat.h =================================================================== RCS file: include/linux/flat.h,v retrieving revision 1.2 diff -u -1 -r1.2 flat.h --- include/linux/flat.h 16 Oct 2002 04:34:28 -0000 1.2 +++ include/linux/flat.h 6 Nov 2002 00:51:25 -0000 @@ -4,2 +4,5 @@ * Copyright (C) 2002 David McCullough <davidm@snapgear.com> + * + * This file provides the definitions and structures needed to + * support uClinux flat-format executables. */
Jivin Paul Mackerras lays it down ... > 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.
-- David McCullough: Ph: +61 7 3435 2815 http://www.SnapGear.com davidm@snapgear.com Fx: +61 7 3891 3630 Custom Embedded Solutions + Security - 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/
| |