Canonical Comments

[Arne Vajhøj]

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.

Even as a consumer of the code it is often interesting to look at
the history.

If you have a problem during an upgrade then it can be helpful to
know if that particular class were changed or not.

Arne

 

[Lew]

Even as a consumer of the code it is often interesting to look at
the history.

If you have a problem during an upgrade then it can be helpful to
know if that particular class were changed or not.

I agree that it is possibly sometimes useful to see a version history, for
some artifacts in some projects. I have stated that in such cases an
auxiliary history document could be useful. The only objection I have is to
inclusion of that history in the source artifact itself.

I've been using the Java API for over ten years now, and not once have I ever
wanted or needed to look up the history of any individual source file for it.

Likewise I've never wanted or needed the source history for any artifact in
any Java API I've used only as a "consumer of the code", including, for
example, log4j, MyFaces, OpenJPA, Apache commons-io, commons-lang, Tomcat,
commons-collections, just to name a few where I have had access to the source
code. In situations where I have seen version history in source code, even in
projects where I was on the development team, it was always a major
distraction and annoyance. This was true even when I sometimes needed to see
the version history for an artifact - if the history was in the artifact, it
was annoying; if it was external to the artifact, it was useful.

Nevertheless for those who have a penchant for swimming in water under the
bridge, I'm all in favor of making version history available to those who want
it. I concede your points in this matter. But you have not made a case for
including the history within the artifacts themselves.

 

[Arne Vajhøj]

I agree that it is possibly sometimes useful to see a version history,
for some artifacts in some projects. I have stated that in such cases
an auxiliary history document could be useful. The only objection I
have is to inclusion of that history in the source artifact itself.

I've been using the Java API for over ten years now, and not once have I
ever wanted or needed to look up the history of any individual source
file for it.

Likewise I've never wanted or needed the source history for any artifact
in any Java API I've used only as a "consumer of the code", including,
for example, log4j, MyFaces, OpenJPA, Apache commons-io, commons-lang,
Tomcat, commons-collections, just to name a few where I have had access
to the source code. In situations where I have seen version history in
source code, even in projects where I was on the development team, it
was always a major distraction and annoyance. This was true even when I
sometimes needed to see the version history for an artifact - if the
history was in the artifact, it was annoying; if it was external to the
artifact, it was useful.

Nevertheless for those who have a penchant for swimming in water under
the bridge, I'm all in favor of making version history available to
those who want it. I concede your points in this matter. But you have
not made a case for including the history within the artifacts themselves.

The reasons for that is more practical:
- if they are in the source code they always comes with the source code
- most source controls make it easy to to have them in the source code

Arne

 

[Lew]

The reasons for that is more practical:
- if they are in the source code they always comes with the source code

Ironically, that is my argument against the practice.

- most source controls make it easy to to have them in the source code

Just because something is easy to do doesn't mean one should do it.

 

[Roedy Green]

It doesn't compile them, it assembles them.

http://cplus.about.com/od/glossary/g/gloscompiled.htm
A compiler is a computer program that transforms human readable source
code of another computer program into the machine readable code that a
CPU can execute.

http://www.thefreedictionary.com/assembler
An assembler is a computer program that converts a set of low-level
symbolic data into machine language

What Javadoc does is neither of those two things. It is more like a
report generator, in that it takes the same data and summarises it
various ways.

In ordinary English, assemble means to pull together various component
parts.

Compile means to produce a collection by assembling material from
other sources.

I think we need a new category for tools like Javadoc. I would call
it a "summariser".
--
Roedy Green Canadian Mind Products
http://mindprod.com

"The universe we observe has precisely the properties we should expect if there is, at bottom, no design, no purpose, no evil, no good, nothing but blind, pitiless indifference."
~ Charles Darwin.

 

[Lew]

Lew wrote, quoted or indirectly quoted someone who said :

http://www.thefreedictionary.com/assembler
An assembler is a computer program that converts a set of low-level
symbolic data into machine language

I didn't claim that Javadoc was an assembler, I claimed that it
assembled the documentation.

What Javadoc does is neither of those two things. It is more like a
report generator, in that it takes the same data and summarises it
various ways.

It doesn't summarize.

In ordinary English, assemble means to pull together various component
parts.

In ordinary English, the Javadoc tool assembles comments into
documentation, exactly as I said.

I think we need a new category for tools like Javadoc.  I would call
it a "summariser".  

It doesn't summarize. It copies the entire Javadoc comment into the
final documentation and adds more details of layout, hyperlinkage and
indexing. It is, if anything, the opposite of summarization; it adds
detail.

 

[Roedy Green]

You're right about dealing with the general case: difficult.

I've got my comment data extractor working. It was easier than I
thought. The problem it turns out is a lot of code without any package
comment at all. I don't have the copyright date or a one line summary
for the minor files in a package. I will have to gradually research
them, or perhaps work out a way to get them from the main program in a
package.


--
Roedy Green Canadian Mind Products
http://mindprod.com

"The universe we observe has precisely the properties we should expect if there is, at bottom, no design, no purpose, no evil, no good, nothing but blind, pitiless indifference."
~ Charles Darwin.

 

[Martin Gregorie]

I think we need a new category for tools like Javadoc. I would call it
a "summariser".

What it does is to extract comments and externally accessible
definitions, cross-reference the definitions and then format this into
something readable.

I'd just call them "documentation generators". I've thought a bit and
can't come up with anything shorter.

 

[Roedy Green]

It doesn't summarize. It copies the entire Javadoc comment into the
final documentation and adds more details of layout, hyperlinkage and
indexing. It is, if anything, the opposite of summarization; it adds
detail.

Other than a strict listing of the javadoc, it prepares an abbreviated
list without the parms. It produces a package list and the classes
list. It produces the uses list. It creates a class hierarchy. It
produces the alphabetic index.

This is roughly analogous to what you do with a report generator,
taking detail data and summarising it in various ways.

"Assemble" is correct in that Javadoc.exe pulls together data from
many source documents to form its collection of HTML.

However assemble has specific meaning already in computing, so I think
it wise to use some other term for what Javadoc does.
--
Roedy Green Canadian Mind Products
http://mindprod.com

"The universe we observe has precisely the properties we should expect if there is, at bottom, no design, no purpose, no evil, no good, nothing but blind, pitiless indifference."
~ Charles Darwin.

 

[Roedy Green]

I'd just call them "documentation generators". I've thought a bit and
can't come up with anything shorter.

It is possible to do other things with the JavaDoc data, by writing
your own processing stubs.

Javadoc is one of the reasons Java has been such a success. It imposed
some order on chaos. I would like to see even more structure,
particularly for the mindless getter/setters.


--
Roedy Green Canadian Mind Products
http://mindprod.com

"The universe we observe has precisely the properties we should expect if there is, at bottom, no design, no purpose, no evil, no good, nothing but blind, pitiless indifference."
~ Charles Darwin.

 

[Martin Gregorie]

I've got my comment data extractor working. It was easier than I
thought. The problem it turns out is a lot of code without any package
comment at all.

Put a "package-info.java" file in the same directory as the source files.
That adds the package-level comment for javadocs, so presumably it could
also be made to work with your script.

 

[Martin Gregorie]

It is possible to do other things with the JavaDoc data, by writing your
own processing stubs.

Javadoc is one of the reasons Java has been such a success. It imposed
some order on chaos. I would like to see even more structure,
particularly for the mindless getter/setters.

Does that change what it does in any substantive way?

AFAICT Doclets don't let you see any more of the source than already
appears in Javadocs output apart from comments inside methods. I may be
missing something, but there's really nothing else I'd like to see in
Javadocs, though sometimes I'd like the change the layout. Taglets do let
you define your own tags, but I'm not sure I need to do that.

 

[Arved Sandstrom]

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.

This is what I do (and some fellow developers), using Subversion. Our
thinking is, if you've got the commit comment you may as well
intelligently use it. Strictly speaking, every commit is traceable to a
change request or a defect (and during initial development it still
reflects some significant modification or other).

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

Eclipse and NetBeans plugins for Subversion do a pretty good job at
displaying version history (with commit comments) for the selected file.
You can also double click on the revision of interest in version history
and open up that revision for inspection (at least in Eclipse).

Most of the time though I just use command line "svn log", either
verbose or with the XML option.

AHS

 

[Arved Sandstrom]

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.

Regardless of the phase of the project - development, testing,
maintenance etc - there shouldn't be a single commit to anything that
isn't traceable to something: software requirement (at one remove
through the design docs), reported defect, change request, and so forth.
As such, given some developer discipline, each and every commit comment
can (and IMHO, should) include traceable information that links to a
defect/change request ID in a defect tracking system, or a design item
in a document.

On J2EE projects I've been working on for some time now, we do this with
a fair bit of success (we're using Subversion). As a result the use of
"svn log" now provides us with a hell of a lot more useful information
than we had, say, a year ago when this system was not in place.
Comfiguration/build managers and PMs now have a much better idea of
what's going on with the codebase.

If your team needs a bit of prodding to adopt the system described, at
least with Subversion you can write a commit hook that requires a
certain format of traceable information somewhere within the body of the
commit comment.

I may have misunderstood you, Martin - I am not sure why
branching/merging would cause problems.

AHS

 

[Arne Vajhøj]

http://cplus.about.com/od/glossary/g/gloscompiled.htm
A compiler is a computer program that transforms human readable source
code of another computer program into the machine readable code that a
CPU can execute.

http://www.thefreedictionary.com/assembler
An assembler is a computer program that converts a set of low-level
symbolic data into machine language

Assembler has a very specific meaning in IT.

But assembles does follow that meaning.

And not even assembler always has this meaning.

<quote>
EE.2.10.3Application Assembler
The Application Assembler takes a set of components developed by
Application Component Providers and assembles them into a complete Java
EE application delivered in the form of an Enterprise Archive (.ear)
file. The Application Assembler will generally use GUI tools provided by
either a Platform Provider or Tool Provider. The Application Assembler
is responsible for providing assembly instructions describing external
dependencies of the application that the Deployer must resolve in the
deployment process.
</quote>

It is left as an exercise to figure out where the quote is from.

Arne

 

[Martin Gregorie]

I may have misunderstood you, Martin - I am not sure why
branching/merging would cause problems.

I thoroughly agree with your approach.

Re the branch/merge point, I was visualizing a proper bug tracking
database either being implemented inside the SVN (which would solve the
problem nicely) or outside with links into the SVN such that searches and
enquiries in the bug tracker could show relevant stuff from the SVN and
vice versa.

IMO a good bug tracker is similar to an SSADM requirements catalogue,
which records requirements and processes in a M:M relationship to reflect
the fact that a requirement may generate several processes just as one
process may be involved in implementing several requirements. A good bug
tracker needs to model this type of relationship between bugs and fixes
as a minumum. Additionally it should be able to record dates and to link
a bad fix to the bugs it generates.

The problems I mentioned, which may well be CVS-centric, can arise if the
codebase is cloned onto a remote site, bugs are spotted and fixed and
then the remote codebase is merged back into the master codebase. CVS can
handle this but no bug tracker I've used could. All have been single
central bug repositories with nothing analogous to an SVN's branch/merge
capabilities.

 

[Roedy Green]

Put a "package-info.java" file in the same directory as the source files.
That adds the package-level comment for javadocs, so presumably it could
also be made to work with your script.

By "package comment" I meant the /* */ comment that goes just above
the package statement that does not appear in JavaDoc. See
http://mindprod.com/jgloss/comments.html
--
Roedy Green Canadian Mind Products
http://mindprod.com

Now for something completely different:

 

[Arne Vajhøj]

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!

The GPL only operates with source code and object code.

It seems obvious to me that the GPL rules for object code
not the GPL rules for source code would apply to Java docs.

The difference between source code and object code GPL license
wise is that if you give somebody source code, then you are OK, but
if you give object code, then you need to give or be willing to give
the source code to allow the receiver to modify what he got.

If the receiver is to be able to change the Java docs then he/she
needs the Java source code.

Arne