19 Oct
2005
19 Oct
'05
3:08 p.m.
Casper Hornstrup wrote:
I'm glad we agree on this point....
I suggest
something as follows:
/*
* PROJECT: ReactOS Kernel
* LICENSE: GPL - See COPYING in the top level directory
* FILE: ntoskrnl/ex/mutant.c
* PURPOSE: section of the kernel
* PROGRAMMERS: Alex Ionescu (alex(a)reactos.org)
* David Welch (welch(a)cwcom.net)
*/
Which is exactly what the kernel uses right now.
Best regards,
Alex Ionescu
[CSH] Yes, less unneeded information is better.
People will tend to forget updating the headers.
Actually I'd prefer if there isn't any
information
in the header which is different from file to file.
..but this is going a bit too far, imho.
You can lookup the information in the PROGRAMMERS
field in the repository. The PURPOSE field is
not needed as you should be able to get the same
information from the filename and the code in the
file.
I agree it can be considered superflous, but having such identification
information is usually considered good practice in most software
projects. While -we- can lookup that information, a non-programmer will
have NO clue what on Earth a file does simply by browsing through it. As
for the PROGRAMMERS information, it can be much more useful and correct
then looking up anyone that ever touched the file. It can also provide
email information, which SVN doesn't. An example: if Foo is browing our
sources to create some documentation, I'm sure he'd prefer knowing the
purpose of each file right out of the bat, and also have contact
information for the main developer(s) so he can ask questions.
If you can't see the purpose from this, then
the code isn't as clear as it could be.
You're assuming everyone is a developer. You're also assuming every
comments their code. There's some stuff in ntoskrnl\mm that I can barely
begin to understand; I don't want to imagine what a non-kernel dev, or
even a non-dev would glean from it.
It's kind
of like documenting your way out of unreadable code.
Microsoft extensively comments their files yet also includes a "Purpose"
field. Almost every software project in the world does.
The information in the FILE field is already
displayed in your editor.
The information the FILE field is generally used when a file has been
moved from its original location (ie: in forked projects) so that the
original may be quickly found. It is invaluable.
We should not
misrepresent or not represent copyrights, so that
should be there. We also reuse code from external
projects and it's important to keep the copyright
notices around. The less information there is to
maintain, the more likely it is kept up to date.
I agree, but stuff like FILE, USAGE and PROGRAMMER don't require that
much maintenance. I would agree with the header below if ReactOS were a
secret project that only super-genius developers have access to, with no
outside forking possible.
/*
* PROJECT: ReactOS Kernel
* LICENSE: GPL - See COPYING in the top level directory
* COPYRIGHT: Copyright (C) 2004-2005 John Doe
* Copyright (C) 2005 Jane Doe
*/
Casper
Best regards,
Alex Ionescu