Canonical Comments

[Roedy Green]

If you lack good ideas, then following:
http://java.sun.com/docs/codeconv/html/CodeConventions.doc10.html#182
would not be the worst thing to do.

in that example is the line:

* @(#)Blah.java 1.82 99/03/18

in a /* comment.

what does the @ mean?
what does the (#) mean?
is the 1.82 generated?
is the 99/03/18 generated?
--
Roedy Green Canadian Mind Products
http://mindprod.com

For most people, a global average temperature rise of 3°C (5°F) does not sound
alarming. They don’t understand that the warming is uneven, mostly over the
continents which will rise 6°C (11°F). The maximum annual temperature will
increase considerably more. Paris will have the temperature of Algiers,
Moscow the temperature of Paris, San Francisco the temperature of Tijuana and
New York the temperature of Charleston, and Houston the temperature of some
obscure dusty town in southern Mexico.

 

[Roedy Green]

I have to agree with Lew that this is something that does not need to be
standardized. The Javadoc tool has its own spec, the rest is programmer
preference.

It would help if each programming team were consistent at least.
--
Roedy Green Canadian Mind Products
http://mindprod.com

For most people, a global average temperature rise of 3°C (5°F) does not sound
alarming. They don’t understand that the warming is uneven, mostly over the
continents which will rise 6°C (11°F). The maximum annual temperature will
increase considerably more. Paris will have the temperature of Algiers,
Moscow the temperature of Paris, San Francisco the temperature of Tijuana and
New York the temperature of Charleston, and Houston the temperature of some
obscure dusty town in southern Mexico.

 

[Roedy Green]

I thought Roedy meant something more widespread than a project, but of
course you're right about standardisation being a good idea for a
project.

I thought I should suggest something and publish it in the Java
glossary for a template to get started with. At least it would remind
you to include the usual information. Then if a newbie left it out, it
would not be inadvertent.

I have also noticed the chaos in my own life body of work. I would
like to bring it to some standard. I thought I would solicit ideas on
what that should look like.
--
Roedy Green Canadian Mind Products
http://mindprod.com

For most people, a global average temperature rise of 3°C (5°F) does not sound
alarming. They don’t understand that the warming is uneven, mostly over the
continents which will rise 6°C (11°F). The maximum annual temperature will
increase considerably more. Paris will have the temperature of Algiers,
Moscow the temperature of Paris, San Francisco the temperature of Tijuana and
New York the temperature of Charleston, and Houston the temperature of some
obscure dusty town in southern Mexico.

 

[Arne Vajhøj]

in that example is the line:

* @(#)Blah.java 1.82 99/03/18

in a /* comment.

what does the @ mean?
what does the (#) mean?
is the 1.82 generated?
is the 99/03/18 generated?

I suspect the entire line is generated by the source control
system.

But I only think the example intends to say that you should
put info about the file and the company disclaimer here - not
that it should be the exact same template.

Arne

 

[Lew]

I disagree.

It is not unusual to distribute source code in .zip/.tar.gz instead
of via CVS/SVN.

That doesn't make it any better to include the version history in each artifact.

It suffices simply to distribute the latest version. Incorporating the entire
history of an artifact in the artifact does little to aid anyone, in the
common case. To protect in the uncommon case, one could include a
version-history report as a separate document, generated by the VC system.

 

[Lew]

I consider it object code not derived source code.

Interesting outlook. That's the first time I've ever heard of HTML in a form
designed for human consumption, not machine consumption, described as "object
code".

That's a singularly inappropriate label. Sure, it's generated, but in no
meaningful sense is it "object code". It's not even "code". It's
*documentation* - that's what the "doc" in "Javadoc" stands for!

 

[Lew]

"Could be" != "should be".


But not in object-code format, not designed for machine consumption, not
"code", and not meant to be linked or executed, only as documentation.

and not exactly generated from source _code_ - it's generated from
non-compilable source _comments_.

 

[Lew]

It would help if each programming team were consistent at least.

The standard Javadoc template and the advice and conventions given in Sun's
documentation provide a reasonable degree of consistency.

 

[Larry K. Wollensham]

So, in your world, HTML code is not "code". OK then.

and not exactly generated from source _code_ - it's generated from
non-compilable source _comments_.

I imagine that Sun would be very surprised to hear that javadoc is
unable to compile doc comments.

 

[Joshua Cranmer]

So, in your world, HTML code is not "code". OK then.

HTML stands for HyperText Markup Language. It is a markup language; it
is not even Turing-complete! Oh wait, you were talking about JavaScript?
Third right, second door on the left.

 

[Martin Gregorie]

It suffices simply to distribute the latest version. Incorporating the
entire history of an artifact in the artifact does little to aid anyone,
in the common case. To protect in the uncommon case, one could include
a version-history report as a separate document, generated by the VC
system.

That only works if the VCS can maintain history at the module or project
level, rather than the individual file level. The last vcs I used that
could do that was ICL's Advanced Data Dictionary System, but that's long
extinct - AFAIK it died with VME/B.

I'm know I'm out of touch here: I currently just use cvs. It has no
concept of anything wider than individual file-level version control[1],
but can svn and git do any better?

[1] Yes, I know that it can commit a bunch of files, applying the same
comment to all of them, but the file version numbers aren't synchronized.

 

[Martin Gregorie]

I have also noticed the chaos in my own life body of work. I would like
to bring it to some standard. I thought I would solicit ideas on what
that should look like.

Having one's own template sounds like a good idea.

I did that some years back for C utilities: I wrote a script that
generates skeleton source, header and manpage files and a Makefile. It
does this by modifying templates. The source contains copyright stuff and
a main() that implements standard command line requirements: 'help' and
'debug' options, etc plus a loop that runs a dummy function against each
non-option argument. The generated source clean compiles and will do
something sensible if it is run.

I've never gotten round to doing the same for Java, but an equivalent
script would be a useful thing to have.

Similarly, a script to inject licensing information into existing
unlicensed Java source files has been near the top of my todo list for
the last month or so.

 

[Lew]

It suffices simply to distribute the latest version. Incorporating the
entire history of an artifact in the artifact does little to aid anyone,
in the common case. To protect in the uncommon case, one could include
a version-history report as a separate document, generated by the VC
system.

That only works if the VCS can maintain history at the module or project
level, rather than the individual file level. The last vcs I used that
could do that was ICL's Advanced Data Dictionary System, but that's long
extinct - AFAIK it died with VME/B.

I'm know I'm out of touch here: I currently just use cvs. It has no
concept of anything wider than individual file-level version control[1],
but can svn and git do any better?

[1] Yes, I know that it can commit a bunch of files, applying the same
comment to all of them, but the file version numbers aren't synchronized.

But it's file-level history of which I speak, "the entire history of an
artifact in the artifact" as I stated.

When you put the entire version history in an artifact, that isn't the project
history. It's the wrongness of file history in the file that is the problem
to which I spoke.

And how is putting the project history in each file better?

 

[Lew]

I imagine that Sun would be very surprised to hear that javadoc is
unable to compile doc comments.

Cute, Larry.

It doesn't compile them, it assembles them.

 

[John B. Matthews]

That only works if the VCS can maintain history at the module or
project level, rather than the individual file level. The last vcs I
used that could do that was ICL's Advanced Data Dictionary System,
but that's long extinct - AFAIK it died with VME/B.

Although my experience is limited, ClearCase [1] seems to handle this.

I'm know I'm out of touch here: I currently just use cvs. It has no
concept of anything wider than individual file-level version
control[1], but can svn and git do any better?

While working on a project where in-file history was the norm, I found
myself habitually copying my most recent comment(s) into the subversion
commit command. Conversely, a requirement to exhibit revision history by
package was easily met by (recursively) feeding package paths to 'svn
log'. It's hard not to consider in-file history redundant.

Many repository viewers, e.g. Trac [2] and ViewVC [3], can display the
subversion logs and diffs meaningfully [4, 5].

[1] <http://en.wikipedia.org/wiki/Rational_ClearCase>
[2] <http://trac.edgewall.org/>
[3] <http://viewvc.tigris.org/>
[4] <http://trac.macports.org/browser>
[5] <http://robotchase.svn.sourceforge.net/viewvc/robotchase/>

 

[Martin Gregorie]

But it's file-level history of which I speak, "the entire history of an
artifact in the artifact" as I stated.

OK, I may have mixed in other parts of the discussion.
The file version history entered into a VCS is the history. Whether its
correct is another matter and the responsibility of whoever commits it,
no matter where its stored, which might be just the VCS audit trail or an
additional copy in the file as well. Here I'd agree with the other poster
who pointed out that sources are frequently distributed as tarballs: in
this having the version history in the file can be rather useful provided
its accurate and correct.

And how is putting the project history in each file better?

Systems like the ICL ADDS held project version details outside any of the
component file version details. This is what I meant, not that project
version details would get into component files.

Having project-level version control has two advantages.

Firstly, you could potentially[1] automatically generate program version
numbers by using the project version number.

Secondly, its easy to apply fixes to production versions of a system
without necessarily[2] impacting later development versions. In ADDS
declaring a new project version effectively froze the previous version's
files and opened a changes space between the two. The effect was that you
*knew* which file versions made up each project version and changes in a
later project version couldn't screw that up. This made it easy to apply
patches to any project version and run a build.

BTW, The ADDS wasn't exactly bleeding edge technology. I was using in in
the early '80s.

[1] I don't think ADDS could do that, but its an obvious enough
requirement.

[2] There was a project-level option that determined whether such patches
affected later project versions or not.

 

[Lew]

On > The file version history entered into a VCS is the history. Whether its
correct is another matter and the responsibility of whoever commits it,
no matter where its stored, which might be just the VCS audit trail or an
additional copy in the file as well. Here I'd agree with the other poster
who pointed out that sources are frequently distributed as tarballs: in
this having the version history in the file can be rather useful provided
its accurate and correct.

I find it less than useless myself. What do I care that braces were
added to the third 'if' clause on Jan. 12 of 2003?

As a client of a class, I care about the correctness today, not what
changes were made a few days, weeks, months or years ago to get it
that way. I care about the Javadocs. Unless I'm actively working on
changing the source, in which case I had *better* be using the source-
code repository myself, the change history is dilatory.

Systems like the ICL ADDS held project version details outside any of the
component file version details. This is what I meant, not that project
version details would get into component files.  

This suggestion makes good sense. I am in favor of keeping history in
separate files for those times when you need it. Project history is
much more useful than individual artifact history to anyone not
directly involved in coding the artifacts.

 

[Roedy Green]

Similarly, a script to inject licensing information into existing
unlicensed Java source files has been near the top of my todo list for
the last month or so.

The hard part is recognising existing information and extracting it,
and tidying it and later throwing it away, without discarding any
gold.

It is pretty easy to write a program that glues a standard header on
the front of each program with standard boilerplate, and a slot for
the filename.

I have an rough idea how I might proceed. The tidier scans the early
part of a program for comments and collects paragraphs. It then tries
to categories paragraphs by strings in them. Then it uses regexes to
extract information from recognised paragraphs.

Then it generates the new header. Any stuff it did not use, it lumps
into an additional info: section of the header where it can manually
be pruned.
--
Roedy Green Canadian Mind Products
http://mindprod.com

For most people, a global average temperature rise of 3°C (5°F) does not sound
alarming. They don’t understand that the warming is uneven, mostly over the
continents which will rise 6°C (11°F). The maximum annual temperature will
increase considerably more. Paris will have the temperature of Algiers,
Moscow the temperature of Paris, San Francisco the temperature of Tijuana and
New York the temperature of Charleston, and Houston the temperature of some
obscure dusty town in southern Mexico.

 

[Martin Gregorie]

This suggestion makes good sense. I am in favor of keeping history in
separate files for those times when you need it. Project history is
much more useful than individual artifact history to anyone not directly
involved in coding the artifacts.

What would be really good during the later stages of development of
moderate to large projects would be the ability to link code changes back
to the bug reporting system. This way there would be a clear connection
between a bug report, discussion and resulting code changes - and the
code itself could be kept uncluttered. However, I can see real problems
in handling code branching and merging, especially if some branches are
worked on offline from the main repository.

 

[Martin Gregorie]

The hard part is recognising existing information and extracting it, and
tidying it and later throwing it away, without discarding any gold.

You're right about dealing with the general case: difficult. That's
probably best handled by something like my C skeleton generator. However,
my licensing verbiage injection task is much simpler, since there's
nothing already there to modify. All it has to do is to inject text into
a new non-Javadoc comment at the page head and/or into the end of the
class-level Javadoc comment.