top-level source header

[Ged]

Although a standard header was drafted out for the ReactOS source code, 
few people seem to use it and it doesn't seem to be in the wiki.

I would like to get something in the wiki agreed on by everyone which 
should be included in our source files.
I think we firstly need have a vote to see if everyone actually wants a 
standard header, but I put together some info anyway to explain my thoughts


As much of the ReactOS code is licensed under the GPL, it can be reused 
by anyone under the license agreements.
As the BSD code does, I think a ReactOS copyright notice should be 
placed in the header to ensure people know where the original code came 
from. Our current header has no provision for this meaning anyone 
reading ReactOS code away from the project won't have a return point.
I was talking this over with Alex, who suggested everyone might not want 
to give copyright to the foundation. Any suggestions?

Using the existing header, I have drafted a slightly modified version

/*
1 * ReactOS <place holder>
2 * Copyright (C) 2005 ReactOS Foundation
3 *
4 * LICENCE:     <place holder>
5 * PROJECT:     <place holder>
6 * FILE:        <place holder>
7 * PURPOSE:     <place holder>
8 * PROGRAMMERS: <place holder>
9 * REVISIONS:
10 *             <place holder>
11 *
*/

1. This is a quick line to state the area which the code was written 
for. Examples could include:
       ReactOS Executive
       ReactOS Win32 Subsystem
       ReactOS Win32 Applications

2. The copyright should detail a date when the copyright was initiated 
along with the date when it was last modified. For example:
       1999 - 2004
The proceeding date should be updated each time a revision is made.

4. This line should state the licence used and where to find the COPYING 
file

5. This line should state what project / binary the code is for. 
Examples could include:
       ReactOS ntdll library
       ReactOS ws2_32 library
       ReactOS arp utility
       ReactOS cache manager
       ReactOS thread scheduler

6. This line should state the location of the file within the repository

7. This line should state the purpose of the project / binary the code 
is intended for

8. This line should state any programmers whom have worked on the code. 
The programmer can also choose to add an email address along with their 
name as a point of contact

9. This line should list any revisions made to the code. The revisions 
should include programmers initials, which can be linked to the 
PROGRAMMERS section, the date the revision was made and a short comment 
describing the revision. This is not meant for bug fixes and small 
modifications, but for feature additions or substantial patches

I think we should put something in the wiki in relation to this.

Does anyone have any other suggestions, or modifications to my header.

Please see the examples below.

Examples:

/*
* ReactOS Win32 Applications
* Copyright (C) 2005 ReactOS Foundation
*
* LICENCE:     GPL - See COPYING in the top level directory
* PROJECT:     ReactOS arp utility
* FILE:        apps/utils/net/arp/arp.c
* PURPOSE:     view and manipulate the ARP cache
* PROGRAMMERS: Ged Murphy (gedmurphy(a)gmail.com)
* REVISIONS:
*              GM 04/10/05 Created
*
*/

/*
* ReactOS Executive
* Copyright (C) 2005 ReactOS Foundation
*
* LICENCE:     GPL - See COPYING in the top level directory
* PROJECT:     ReactOS kernel
* FILE:        ntoskrnl/ex/mutant.c
* PURPOSE:     section of the kernel
* PROGRAMMERS: Alex Ionescu (alex(a)reactos.org)
*              David Welch (welch(a)cwcom.net)
* REVISIONS:
*              AI 04/10/05 Fix tab/space mismatching, tiny fixes to 
query function and
*               add more debug output.
*
*/

/*
* ReactOS Network Stack
* Copyright (C) 2000 - 2005 ReactOS Foundation
*
* LICENCE:     GPL - See COPYING in the top level directory
* PROJECT:     ReactOS TCP/IP protocol driver
* FILE:        transport/tcp/tcp.c
* PURPOSE:     Transmission Control Protocol
* PROGRAMMERS: Casper S. Hornstrup (chorns(a)users.sourceforge.net)
*              Art Yerkes (arty(a)users.sf.net)
* REVISIONS:
*              CSH 01/08-2000 Created
*              AY 12/21/2004 Added accept
*/

[Alex Ionescu]

Ged wrote:

>   Although a standard header was drafted out for the
> ReactOS source 
>  code, few people seem to use it and it doesn't seem to be in the wiki. 
Agreed, I will setup a vote on it ASAP.

>  
>  I would like to get something in the wiki agreed on by everyone which 
>  should be included in our source files.
>  I think we firstly need have a vote to see if everyone actually wants 
>  a standard header, but I put together some info anyway to explain my 
>  thoughts
>
>
>  As much of the ReactOS code is licensed under the GPL, it can be 
>  reused by anyone under the license agreements.
>  As the BSD code does, I think a ReactOS copyright notice should be 
>  placed in the header to ensure people know where the original code 
>  came from. Our current header has no provision for this meaning anyone 
>  reading ReactOS code away from the project won't have a return point.
>  I was talking this over with Alex, who suggested everyone might not 
>  want to give copyright to the foundation. Any suggestions?
>
>  Using the existing header, I have drafted a slightly modified version
>
>  /*
>  1 * ReactOS <place holder>
>  2 * Copyright (C) 2005 ReactOS Foundation
>  3 *
>  4 * LICENCE:     <place holder>
>  5 * PROJECT:     <place holder>
>  6 * FILE:        <place holder>
>  7 * PURPOSE:     <place holder>
>  8 * PROGRAMMERS: <place holder>
>  9 * REVISIONS:
>  10 *             <place holder>
>  11 *
>  */
>
>  1. This is a quick line to state the area which the code was written 
>  for. Examples could include:
>        ReactOS Executive
>        ReactOS Win32 Subsystem
>        ReactOS Win32 Applications 
Unnecessary, the "PROJECT" line should already state this.

>  
>  2. The copyright should detail a date when the copyright was initiated 
>  along with the date when it was last modified. For example:
>        1999 - 2004
>  The proceeding date should be updated each time a revision is made. 
As I've stated, you cannot claim Copyright to the ReactOS foundation 
unless EVERY developer that has touched that file agrees to it. This 
would require significant administrative resources as well as locating 
any previous project members. And that still doesn't guarantee that they 
will all agree to give copyright to the foundation. As it stands, 
copyright belongs to the actual developers that have written the file.

>  
>  4. This line should state the licence used and where to find the 
>  COPYING file
>
>  5. This line should state what project / binary the code is for. 
>  Examples could include:
>        ReactOS ntdll library
>        ReactOS ws2_32 library
>        ReactOS arp utility
>        ReactOS cache manager
>        ReactOS thread scheduler
>
>  6. This line should state the location of the file within the repository
>
>  7. This line should state the purpose of the project / binary the code 
>  is intended for
>
>  8. This line should state any programmers whom have worked on the 
>  code. The programmer can also choose to add an email address along 
>  with their name as a point of contact
>
>  9. This line should list any revisions made to the code. The revisions 
>  should include programmers initials, which can be linked to the 
>  PROGRAMMERS section, the date the revision was made and a short 
>  comment describing the revision. This is not meant for bug fixes and 
>  small modifications, but for feature additions or substantial patches 
When some of us unofficially discussed the project header, we determined 
it was not a good idea to have a revision entry for 3 simple facts:
1) Waste of space
2) Duplicate information, we have SVN for this
3) Even disregarding the first two reasons, if you look back at when 
this was used, almost no developers actually update the revision field. 
Few of them even upgrade the "programmer" field. A lot of files have 
David Welch in the kernel simply because his original header was copied 
everywhere. Developers which actually worked on the file often don't 
appear at all. Getting people to update the revisions field would be 
even harder. Additionally, it's completely unnecessary since SVN is 
there for that (and this was the original argument that was made against 
it).

>  
>  I think we should put something in the wiki in relation to this. 
Add it to the coding guidelines I guess.

>  
>  Does anyone have any other suggestions, or modifications to my header. 
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

[Casper Hornstrup]

>   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.
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. If you can't see the purpose from this, then
the code isn't as clear as it could be. It's kind
of like documenting your way out of unreadable code.
The information in the FILE field is already
displayed in your editor. 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.

/*
 * 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

[Ge van Geldorp]

>   From: Casper Hornstrup
>  
>  /*
>   * PROJECT:   ReactOS Kernel
>   * LICENSE:   GPL - See COPYING in the top level directory
>   * COPYRIGHT: Copyright (C) 2004-2005 John Doe
>   *            Copyright (C) 2005 Jane Doe
>   */ 
I may be nitpicking here, not being a lawyer and all, but: I was told that
(C) is not a valid replacement for the "C in a circle" copyright symbol.
Therefor, it is better to leave the (C) out:

/*
 * PROJECT:   ReactOS Kernel
 * LICENSE:   GPL - See COPYING in the top level directory
 * COPYRIGHT: Copyright 2004-2005 John Doe
 *            Copyright 2005 Jane Doe
 */

The US Copyright Office says on their website
http://www.copyright.gov/circs/circ1.html#noc (hope I don't violate
copyright by quoting this, I think it's fair use <g>):

[begin quote]
The notice for visually perceptible copies should contain all the following
three elements:

1. The symbol C (the letter C in a circle), or the word "Copyright," or the
abbreviation "Copr."; and

2. The year of first publication of the work. In the case of compilations or
derivative works incorporating previously published material, the year date
of first publication of the compilation or derivative work is sufficient.
The year date may be omitted where a pictorial, graphic, or sculptural work,
with accompanying textual matter, if any, is reproduced in or on greeting
cards, postcards, stationery, jewelry, dolls, toys, or any useful article;
and

3. The name of the owner of copyright in the work, or an abbreviation by
which the name can be recognized, or a generally known alternative
designation of the owner.
[end quote]

Ge van Geldorp

[Casper Hornstrup]

>   -----Original Message-----
>  From: ros-dev-bounces(a)reactos.org [mailto:[e-mail]] On Behalf Of Ge
> van Geldorp
>  Sent: 19. oktober 2005 09:57
>  To: 'ReactOS Development List'
>  Subject: RE: [ros-dev] top-level source header
>  
> >   From: Casper Hornstrup
> >
> >  /*
> >   * PROJECT:   ReactOS Kernel
> >   * LICENSE:   GPL - See COPYING in the top level directory
> >   * COPYRIGHT: Copyright (C) 2004-2005 John Doe
> >   *            Copyright (C) 2005 Jane Doe
> >   */ 
>  
>  I may be nitpicking here, not being a lawyer and all, but: I was told that
>  (C) is not a valid replacement for the "C in a circle" copyright symbol.
>  Therefor, it is better to leave the (C) out:
>   
[CSH] Yes, I've heard that before.

Casper

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

[Casper Hornstrup]

>   -----Original Message-----
>  From: ros-dev-bounces(a)reactos.org [mailto:[e-mail]] On Behalf Of Alex
> Ionescu
>  Sent: 19. oktober 2005 17:08
>  To: ReactOS Development List
>  Subject: Re: [ros-dev] top-level source header
>  
>  Casper Hornstrup wrote:
>  
> >  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. 
[CSH] I'm
wondering why it is considered good practice. If a non-programmer
has no clue as to what the file contents does from reading the source code,
why does he need to know the information contained in a one line summary
description of the file contents?

As
>   for the PROGRAMMERS information, it can be much more
> useful and correct
>  then looking up anyone that ever touched the file. 
[CSH] Well history has proved
that statement wrong. We have had and still
have files with headers which were just copied from another file and not
changed, so it has the wrong information in it. I'm sure you have seen that
when you worked on ntoskrnl. The repository has correct information when
the committer was the author and when he isn't, it is usually practised that
the original author is mentioned in the commit message.

It can also provide
>   email information, which SVN doesn't. 
[CSH]
People change e-mail addresses all the time. During this project,
I've had at least 5 difference e-mail addresses. Repository usernames
don't change. When you change e-mail address, do you run through all
the headers and change it? I'm sure many people wouldn't.

We can maintain e-mail addresses at:
http://www.reactos.org/wiki/index.php/Committers
then you only need to change it in one central place.

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. 
[CSH] Tell him to browse using ViewCVS. He can get the username from there.
If he is too lazy to look up the e-mail address of the committer, then we
can create a website that does it for him. Still way much less work than
maintaining that information on 10.000+ files in the future. And when you
re-arrange the structure of the code (like for instance your ntoskrnl
changes), the purpose of the files may change and you need to update the
purpose descriptions. Extra work when developing and history tells us that
developers forget about such things possible because the compiler doesn't
warn about it.

> >  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. 
[CSH] You don't need comments to make code
understandable. Maybe that code
could need some refactoring? What I would really like to know now is, why
is a non-programmer reading source code for a piece of highly complex
software like ReactOS?

>   
> >  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.
>  
[CSH] Possibly. I couldn't say as I haven't looked at almost every
software
project in the world. I'm still wondering, why do they do it?

> >  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. 
[CSH] ...if it were kept up to
date, which we seem to have a great
number of problems doing. Why is it invaluable to know the location within
the repository when it was forked? It may have changed since then.

>   
> >  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. 
[CSH] Still a lot more than none. There are ~5700 C/C++ files in
the
reactos module. The average space taken up by the FILE, PURPOSE and
PROGRAMMERS fields the 3 headers below is 183 bytes (without the revision
changes descriptions). That is 994KB of text for 5700 files or an
additional 1 minute download time (128Kbit ADSL). And let me just point
out that ReactOS is still very, very small compared to other mainstream
Operating Systems. Only a 16MB download at present. Normally I don't care
much if additional space is used, but this is for information which is
already present elsewhere.

Let's see some examples.

/*
 * COPYRIGHT:       See COPYING in the top level directory
 * PROJECT:         ReactOS kernel
 * FILE:            ntoskrnl/ke/main.c
 * PURPOSE:         Initalizes the kernel
 *
 * PROGRAMMERS:     Alex Ionescu (cleaned up code, moved Executiv stuff to ex/init.c)
 *                  David Welch (welch(a)cwcom.net)
 */

So main.c initializes the kernel? Why don't we just rename that file to
initialize_kernel.c? Or just initialize.c and rename the parent directory
ke to kernel. Both would give us the same information.

/*
 * COPYRIGHT:       See COPYING in the top level directory
 * PURPOSE:         ReactOS kernel
 * FILE:            ntoskrnl/ke/kqueue.c
 * PURPOSE:         Implement device queues
 *
 * PROGRAMMERS:     Alex Ionescu (alex(a)relsoft.net) - Several optimizations and implement
 *                                                    usage of Inserted flag + reformat
and
 *                                                    add debug output.
 *                  David Welch (welch(a)mcmail.com)
 */

Device_queue.c anyone?

/* $Id: sem.c 15164 2005-05-09 01:38:29Z sedwards $
 *
 * COPYRIGHT:       See COPYING in the top level directory
 * PROJECT:         ReactOS kernel
 * FILE:            ntoskrnl/ke/sem.c
 * PURPOSE:         Implements kernel semaphores
 *
 * PROGRAMMERS:     David Welch (welch(a)mcmail.com)
 */

Semaphore.c? But wait, Subversion says Steven changed the file
last time, yet he's not mentioned in the PROGRAMMERS field.
Is Subversion lying? Was David the only person making changes
to this file?

Actually, Subversion tells us that David didn't even write
half of those lines in the newest revision. A total of 9
people contributed to the file in the newest revision:
http://www.csh-consult.dk/sem_c.txt.
What good is this header information to anyone?

Casper

>  
>
> >   -----Original Message-----
> >  From: ros-dev-bounces(a)reactos.org [mailto:[e-mail]]
> >  On Behalf Of Alex Ionescu
> >  Sent: 19. oktober 2005 17:08
> >  To: ReactOS Development List
> >  Subject: Re: [ros-dev] top-level source header
> >
> >  Casper Hornstrup wrote:
> >
> > >  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. 
>  [CSH]
> I'm wondering why it is considered good practice. If a
>  non-programmer
>  has no clue as to what the file contents does from reading the source
>  code,
>  why does he need to know the information contained in a one line summary
>  description of the file contents? 
These lines help a lot to get a very quick overview about what the file
does, without the need to read the whole file, especially I don't know
anything about this area but need quick infos, e.g. for tracking down with
file or function causes the error/crash/whatever... And this help to save
time of the experts in this area by giving more information about the
issue
Additionaly it helps to find unneeded files

We have a lot of files with copyright 2005 Reactos or similiar. So on
sylvester we must change all files? can't the put the year in one general
file or generate it automatically in SVN?

[Casper Hornstrup]

>   -----Original Message-----
>  From: ros-dev-bounces(a)reactos.org [mailto:[e-mail]] On Behalf Of
>  michael(a)fritscher.net
>  Sent: 19. oktober 2005 20:21
>  To: ReactOS Development List
>  Subject: RE: [ros-dev] top-level source header
>
>  These lines help a lot to get a very quick overview about what the file
>  does, without the need to read the whole file, especially I don't know
>  anything about this area but need quick infos, e.g. for tracking down with
>  file or function causes the error/crash/whatever... And this help to save
>  time of the experts in this area by giving more information about the
>  issue
>  Additionaly it helps to find unneeded files 
[CSH] Can you provide an example where it helps to get a quick overview of
what the file does? And one where it helps find unneeded files?

>   We have a lot of files with copyright 2005 Reactos or
> similiar. So on
>  sylvester we must change all files? can't the put the year in one general
>  file or generate it automatically in SVN? 
[CSH] Who is sylvester? Heh, the copyright year is when the work was written or
modified. Just because the year changes, it doesn't mean the work is modified.

Casper

[Alex Ionescu]

Casper Hornstrup wrote:

>    
>
> >  -----Original Message-----
> > From: ros-dev-bounces(a)reactos.org [mailto:[e-mail]] On Behalf Of Alex
> > Ionescu
> > Sent: 19. oktober 2005 17:08
> > To: ReactOS Development List
> > Subject: Re: [ros-dev] top-level source header
> >
> > Casper Hornstrup wrote:
> >
> >     
> >
> > >  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.
> >     
> >  
> [CSH] I'm wondering why it is considered good practice. If a non-programmer
> has no clue as to what the file contents does from reading the source code,
> why does he need to know the information contained in a one line summary
> description of the file contents?
>   
>  
I gave an example why below... this question is irrelevant if you had 
read my whole email. I'll say the sample again: documentators.

>  As
>   
>
> >  for the PROGRAMMERS information, it can be much
> > more useful and correct
> > then looking up anyone that ever touched the file.
> >     
> >  
> [CSH] Well history has proved that statement wrong. We have had and still
> have files with headers which were just copied from another file and not
> changed, so it has the wrong information in it. I'm sure you have seen that
> when you worked on ntoskrnl. The repository has correct information when
> the committer was the author and when he isn't, it is usually practised that
> the original author is mentioned in the commit message.
>   
>  
You keep avoiding the point: these files might one day find themselves 
OUTSIDE the repository!

>  It can also provide
>   
>
> >  email information, which SVN doesn't.
> >     
> >  
> [CSH] People change e-mail addresses all the time. During this project,
> I've had at least 5 difference e-mail addresses. Repository usernames
> don't change. When you change e-mail address, do you run through all
> the headers and change it? I'm sure many people wouldn't.
>
> We can maintain e-mail addresses at:
> http://www.reactos.org/wiki/index.php/Committers
> then you only need to change it in one central place.
>
> 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.
> >     
> >  
> [CSH] Tell him to browse using ViewCVS. He can get the username from there.
>   
>  
He'll need to go through 30-40 usernames, then figure out which username 
actually wrote useful code. That would take HOURS.

>  If he is too lazy to look up the e-mail address of the
> committer, then we
> can create a website that does it for him. Still way much less work than
> maintaining that information on 10.000+ files in the future. 
>  
Funny how every other project can...but we can't? What's to hard about 
adding a purpose to a file? If I can do it, so can other devs (and they 
do, almost everyone here uses a top-level header).

>  And when you
> re-arrange the structure of the code (like for instance your ntoskrnl
> changes), the purpose of the files may change and you need to update the
> purpose descriptions. Extra work when developing and history tells us that
> developers forget about such things possible because the compiler doesn't
> warn about it.
>
>   
>
> > >  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.
> >     
> >  
> [CSH] You don't need comments to make code understandable.
>  
Nor do you need legs, arms, ears and eyes to live.

>   Maybe that code
> could need some refactoring? 
>  
If you think refactoring solves the necessity of comments, I'm afraid 
you need to revise that notion. Comments are not meant to explain WHAT 
the code does all the time, but more importantly WHY it does it. When 
you deal with technical code, sometimes you can do things which don't 
make a lot of sense unless they are commented. If you look at the DDK 
sample code, some race conditions were found by Microsoft developers 
after YEARS of testing. And sometimes a line or two of code had to be 
added. If you don't comment it, nobody is going to guess why it's there, 
as many times as you refactor.

Not commenting code is totally bad practice.

>  What I would really like to know now is, why
> is a non-programmer reading source code for a piece of highly complex
> software like ReactOS?
>   
>  
I've already answered this. Source code is not only for the "elite",
you 
know. If only programmers would look at source code, then FOSS wouldn't 
have gained the major popularity it has now. The whole point is that 
even a 10 year old can look at source code and fix something really 
stupid, like:

/* Check if we should do FOO */
if (Foo == FALSE) DoFoo;

>    
>
> > >  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.
> >
> >     
> >  
> [CSH] Possibly. I couldn't say as I haven't looked at almost every
> software
> project in the world. I'm still wondering, why do they do it?
>   
>  
Look at WINE, Linux, Solaris, Windows...

>    
>
> > >  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.
> >     
> >  
> [CSH] ...if it were kept up to date, which we seem to have a great
> number of problems doing. Why is it invaluable to know the location within
> the repository when it was forked? It may have changed since then.
>   
>  
Better then nothing!

>    
>
> > >  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.
> >     
> >  
> [CSH] Still a lot more than none. There are ~5700 C/C++ files in the
> reactos module. The average space taken up by the FILE, PURPOSE and
> PROGRAMMERS fields the 3 headers below is 183 bytes (without the revision
> changes descriptions). That is 994KB of text for 5700 files or an
> additional 1 minute download time (128Kbit ADSL). And let me just point
> out that ReactOS is still very, very small compared to other mainstream
> Operating Systems. Only a 16MB download at present. 
>  
Now that's ironic. When I argued about some build changes which caused a 
~2-4MB reduction in that 16MB I was told that "Who cares about 2-4MB". 
Now we have to care about 994KB?

>  Normally I don't care
> much if additional space is used, but this is for information which is
> already present elsewhere.
>
> Let's see some examples.
>
> /*
>  * COPYRIGHT:       See COPYING in the top level directory
>  * PROJECT:         ReactOS kernel
>  * FILE:            ntoskrnl/ke/main.c
>  * PURPOSE:         Initalizes the kernel
>  *
>  * PROGRAMMERS:     Alex Ionescu (cleaned up code, moved Executiv stuff to ex/init.c)
>  *                  David Welch (welch(a)cwcom.net)
>  */
>
> So main.c initializes the kernel? Why don't we just rename that file to
> initialize_kernel.c? Or just initialize.c and rename the parent directory
> ke to kernel. Both would give us the same information.
>
> /*
>  * COPYRIGHT:       See COPYING in the top level directory
>  * PURPOSE:         ReactOS kernel
>  * FILE:            ntoskrnl/ke/kqueue.c
>  * PURPOSE:         Implement device queues
>  *
>  * PROGRAMMERS:     Alex Ionescu (alex(a)relsoft.net) - Several optimizations and implement
>  *                                                    usage of Inserted flag + reformat
> and
>  *                                                    add debug output.
>  *                  David Welch (welch(a)mcmail.com)
>  */
>
> Device_queue.c anyone?
>
> /* $Id: sem.c 15164 2005-05-09 01:38:29Z sedwards $
>  *
>  * COPYRIGHT:       See COPYING in the top level directory
>  * PROJECT:         ReactOS kernel
>  * FILE:            ntoskrnl/ke/sem.c
>  * PURPOSE:         Implements kernel semaphores
>  *
>  * PROGRAMMERS:     David Welch (welch(a)mcmail.com)
>  */
>
> Semaphore.c? But wait, Subversion says Steven changed the file
> last time, yet he's not mentioned in the PROGRAMMERS field.
> Is Subversion lying? Was David the only person making changes
> to this file?
>
> Actually, Subversion tells us that David didn't even write
> half of those lines in the newest revision. A total of 9
> people contributed to the file in the newest revision:
> http://www.csh-consult.dk/sem_c.txt.
> What good is this header information to anyone?
>   
>  
NONE. That's why we need to get people to start using it properly (let's 
have a vote). If peopel decide against top-level headers, then fine, I 
won't insist.

>  Casper
>
>   
>  
Best regards,
Alex Ionescu

[Casper Hornstrup]

>   -----Original Message-----
>  From: ros-dev-bounces(a)reactos.org [mailto:[e-mail]] On Behalf Of Alex
> Ionescu
>  Sent: 19. oktober 2005 23:58
>  To: ReactOS Development List
>  Subject: Re: [ros-dev] top-level source header
>  
>  Casper Hornstrup wrote:
>  I gave an example why below... this question is irrelevant if you had
>  read my whole email. I'll say the sample again: documentators. 
[CSH] What would they document based on that one line mandatory description
of the file contents?

>   
> >  As
> >
> >
> > >  for the PROGRAMMERS information, it can be much
> > > more useful and correct
> > > then looking up anyone that ever touched the file.
> > >
> > >  
> > [CSH] Well history has proved that statement wrong. We have had and still
> > have files with headers which were just copied from another file and not
> > changed, so it has the wrong information in it. I'm sure you have seen that
> > when you worked on ntoskrnl. The repository has correct information when
> > the committer was the author and when he isn't, it is usually practised that
> > the original author is mentioned in the commit message.
> >
> >  
>  You keep avoiding the point: these files might one day find themselves
>  OUTSIDE the repository!
>   
[CSH] Again, why is it important to know the original file location when it
was forked? Assuming the file is reused in its entirety and not in parts, the
file may be moved in the repository since. So we have maintaining such a file
location field on all files against the chance that one might need to easily
locate the file in the repository (assuming the information is still intact
in the fork and that the file isn't moved in the repository). Searching or
grepping for parts of the file contents is another way to find the file in
the repository. I don't consider it worth our resources.

> >  [CSH] Tell him
> > to browse using ViewCVS. He can get the username from there.
> >
> >  
>  He'll need to go through 30-40 usernames, then figure out which username
>  actually wrote useful code. That would take HOURS. 
[CSH] Describe in wiki how to do
this. Run svn blame and pick the username
which occur on most lines. In my previous example, he would have chosen David
since he was listed in the PROGRAMMERS field, but a lot of other people
contributed to that file so it wouldn't have helped him.

>   
> >  If he is too lazy to look up the e-mail address of
> > the committer, then we
> > can create a website that does it for him. Still way much less work than
> > maintaining that information on 10.000+ files in the future.
> >  
>  Funny how every other project can...but we can't? What's to hard about
>  adding a purpose to a file? If I can do it, so can other devs (and they
>  do, almost everyone here uses a top-level header). 
[CSH] Well, go through svn
history and ask developers why they didn't do it.
>    
> >   Maybe that code
> > could need some refactoring?
> >  
>  If you think refactoring solves the necessity of comments, I'm afraid
>  you need to revise that notion. Comments are not meant to explain WHAT
>  the code does all the time, but more importantly WHY it does it. When
>  you deal with technical code, sometimes you can do things which don't
>  make a lot of sense unless they are commented. If you look at the DDK
>  sample code, some race conditions were found by Microsoft developers
>  after YEARS of testing. And sometimes a line or two of code had to be
>  added. If you don't comment it, nobody is going to guess why it's there,
>  as many times as you refactor.
>  
>  Not commenting code is totally bad practice. 
[CSH] I said maybe. I agree that comments are for WHY, but many times
they are WHAT comments. Still there no reason to mandate a one line
description of the file contents if it is clear from the source code or
file/directory structure. If that is not enough then write a comment at
the top of the file.

>   
> >  What I would really like to know now is, why
> > is a non-programmer reading source code for a piece of highly complex
> > software like ReactOS?
> >
> >  
>  I've already answered this. Source code is not only for the "elite",
> you
>  know. If only programmers would look at source code, then FOSS wouldn't
>  have gained the major popularity it has now. The whole point is that
>  even a 10 year old can look at source code and fix something really
>  stupid, like:
>  
>  /* Check if we should do FOO */
>  if (Foo == FALSE) DoFoo;
>   
[CSH] I don't believe we should write the source code for 10 year olds.
reading such code as in your example is confusing since now I have twice as
much information to read through to figure out what it does. I assume you
meant to write "if (Foo == TRUE) DoFoo;", otherwise that would be confusing.

> >  [CSH] Possibly.
> > I couldn't say as I haven't looked at almost every software
> > project in the world. I'm still wondering, why do they do it?
> >
> >  
>  Look at WINE, Linux, Solaris, Windows...
>   
[CSH] I'm sure, but my question still stands. Why?

> >  
> >  
>  Better then nothing! 
[CSH] At a price.

> >  [CSH] Still a
> > lot more than none. There are ~5700 C/C++ files in the
> > reactos module. The average space taken up by the FILE, PURPOSE and
> > PROGRAMMERS fields the 3 headers below is 183 bytes (without the revision
> > changes descriptions). That is 994KB of text for 5700 files or an
> > additional 1 minute download time (128Kbit ADSL). And let me just point
> > out that ReactOS is still very, very small compared to other mainstream
> > Operating Systems. Only a 16MB download at present.
> >  
>  Now that's ironic. When I argued about some build changes which caused a
>  ~2-4MB reduction in that 16MB I was told that "Who cares about 2-4MB".
>  Now we have to care about 994KB? 
[CSH] Only if I were the one to present that argument I think ;-)
Can you point me to the "who cares about 2-4MB" argument please?

Casper