[ksh93-integration-discuss] Re: [osol-code] (CDDL) copyright notice and the ("new") year 2007...

[Casper.Dik at sun.com]

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