[ros-dev] top-level source header

[Alex Ionescu]

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.
>>
>>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