19 Oct
2005
19 Oct
'05
5:31 p.m.
-----Original Message-----
From: ros-dev-bounces(a)reactos.org [mailto:ros-dev-bounces@reactos.org] 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:
[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
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. 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. 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.