>... slightly offtopic: Somewhere on my wishlist is an item to "...
>return to the good old Unix days where names of the authors and some
>rougth change summary is included in the file header...".
>Yes, I know... it's not a replacement for a full line/chunk-based source
>code annotation but I liked the personal touch... and the emails of the
>people who could be contacted for help (the Solaris codebase completely
>lacks that, making it difficult to figure out who knows the matching
>code better than others).
As a purist, I believe that code change comments or author
names do not belong in source code. There are several reasons
for that:
- The amount of change is huge and unwieldy; if you prepend each
source file with the Changelog, there would be tons of stuff
that over times becomes less and less relevant.
And this is for changes for "added features" (RFEs).
When you remove a person's changes, you suddenly also need
to remove their changelog entry because it is no longer relevant.
With a proper source code control mechanism, this is all largely
automatic, you can find changes and the fact that they are no
longer relevant.
- Comments about fixed bugs are COMPLETELY irrelevant.
The bug is fixed, it no longer exists in the code. So what
does the comment refer to? The code should have been written
without the particular changelog entry, so the changelog entry
should not be there.
(Of course, if a bug fix requires a clarifying comment with
a piece of code than that is fine; but only in order to explain
that the algorithm is more difficult than one might initially
think)
- Changelog entries in a file need maintenance too; there is no
mechanism to point to the lines of code changes. Variables
in comments are generally not indexed but if changed, changelog
entries referring to them should be updated too, if those
entries are an integral part of the source.
The source is the source; it could have been written correctly and
efficiently the first time (so it would be like it is now); the changelog
entries are therefor pointless; they only illustrate past mistakes.
Casper
_______________________________________________
opensolaris-code mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/opensolaris-code
