[ros-dev] top-level source header
ionucu at videotron.ca
Wed Oct 19 17:08:21 CEST 2005
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 at reactos.org)
>> * David Welch (welch at cwcom.net)
>>Which is exactly what the kernel uses right now.
>[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
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.
>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
More information about the Ros-dev