RE: [ros-dev] top-level source header

[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