Casper Hornstrup wrote:
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@reactos.org)
David Welch (welch@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.
I'm glad we agree on this point....
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