Skip to end of metadata
Go to start of metadata

A proposed template for the comments block which begins every Java source code file. This block identifies the name and purpose of the file, and provides copyright information; it may also be incorporated into JavaDoc documentation.

This template is being suggested for use by the Services Team, and may also be optionally used by other project teams and contributors, per Issue CSPACE-79.

It is also possible that some variation of this comments block could be selectively incorporated into source code files in other programming or scripting languages (e.g. JavaScript), configuration files, schema files, and other software development-related artifacts of the CollectionSpace project.

Java Beginning Comments Block Template

A commented version of this template follows:

Comments on this template:

Line 9: For "{Contributing Institution}", substitute the name of the institution or other entity that will hold the copyright for this file. Example (for the Services Team): Regents of the University of California.

There is a copyright symbol on this line (the uppercase letter "C' in a circle), entered as a Unicode (UTF-8 encoding) character, which is apparently required to assert copyright in some countries. (If you encounter problems compiling source files containing this character, or any other processing issues, please see the note below.)

A note about the copyright symbol on Line 9

Icon

The copyright symbol on Line 9 was originally entered into this template as the Unicode character in the UTF-8 encoding with the Unicode code point value 'U+00A9', or 'C2 A9' in hexadecimal.

From an initial read of relevant literature, substitutes for that symbol, such as the word "Copyright," may be sufficient as an assertion of copyright in some contexts, but there are some jurisdictions worldwide that are said to still require, or prefer, the presence of this actual copyright symbol. World copyright law is shaped by a melange of various International and bilateral treaties; at least one of those treaties, the Universal Copyright Convention in 1955 in Geneva, apparently requires the actual copyright symbol to "guarantee protection for a copyrighted work in all UCC member countries." (For instance, as partial background, see this Google Quick View of a PDF version of US Copyright Office Information Circular 3, dated January 2008.)

If the inclusion of this character causes problems in any machine processing context, it may be removed from source files. However, before doing so, you might try ensuring that your text editor, or the editor in your integrated development environment (IDE), saves your Java source files in the Unicode UTF-8 encoding, which may resolve those problems. Two examples of how to do this:

  • Eclipse: In the Eclipse Ganymede release, encoding of text files can be set in Window > Preferences > General > Workspace > Text file encoding, as described in this help page.
  • NetBeans: NetBeans 6.7's Help documentation states that, "For a new IDE installation, UTF-8 encoding is the default for new projects." To verify or change NetBeans' per-project encoding of text files, see this wiki page.

Java Class Documentation Template

Icon

The Subversion keyword anchors listed below have become obsolete, following the move of the project's source code from Subversion to Git.

After the comments block, the following class documentation template is also recommended.

Comments on this template:

Line 6: For "{Name of this Class}", substitute the name of the class (without the ".java" extension). Example: "CollectionObjectResource"

Line 8: For "{Purpose of this Class}", substitute a brief summary of the purpose of the class. Example: "Handles web services requests for collection objects."

Line 10: For "{Other Notes Relating to This Class (Optional)}", optionally add other notes pertinent to this class.

There are many excellent examples of "other pertinent notes" in Sun's documentation for its Java classes, particularly in interfaces and abstract classes for major packages in the core Java language. Some other starting point suggestions about what might go into such notes are provided in Scott W. Ambler's Writing Robust Java Code, in the PDF copy of his full guide on that page, at numbered page 36 (physical page 43). Two illustrative examples:

  • "Any good things to know about a class, for example is it part of a pattern or are there any interesting limitations to using it ..."
  • The concurrency strategy used by the class, if any.

Lines 12 and 13: These are Subversion keyword anchors; essentially, special tags that can be auto-expanded with useful information when you commit changes to your files. If keyword substitution properties are enabled, as described further below, these keyword anchors will be automatically filled in with several pertinent details of the last check-in (commit) for this class file:

  • $LastChangedRevision: $
    The revision number associated with the last check-in of this file will be automatically filled in, following the colon.
  • $LastChangedDate: $
    A timestamp for when this file was last checked in will be automatically filled in, following the colon.

These longer keyword anchors, each beginning with "LastChanged...", are preferred to their shorter synonyms, "Revision" and "Date," because by providing more complete descriptions they help avoid ambiguity in their meaning.

Enabling SVN Keyword Substitution Properties for Your Files

By enabling Subversion's keyword substitution properties on your source files, details of the last relevant check-in (commit) - such as the revision number and date of change - can be automatically added to those files. This can be useful information for code users and maintainers.

For a discussion of how keyword substitution works, please see the "Keyword Substitution" chapter of the Subversion manual.

You'll need to set the following two properties, which correspond to the three keyword anchors in the proposed template:

  • Revision (corresponding to "LastChangedRevision")
  • Date (corresponding to "LastChangedDate"

Note that any per-file Subversion property changes - including those related to keyword substitution - are local, so they will need to be committed like any other changes in order to take effect. Only after doing so will you see keyword substitution values, such as the last relevant revision number and date, automatically filled in ("expanded") within your source files.

Setting SVN Keyword Substitution Properties Automatically for Newly Added Files

The easiest way to do this is to set keyword substitution properties automatically for each newly added and committed file. You can do this by editing your local Subversion configuration file, as described in the blog posts Subversion Auto Properties and Subversion and keyword substitition. This method will work with the command-line 'svn' client, as well as with some GUI Subversion clients that pick up settings from that configuration file.

As a brief summary, in that configuration file, you will first set the 'enable-auto-props = yes' directive, and then specify that keyword anchors are to be expanded for one or more file types, specified by filename patterns that may use wildcards, as in this example:

(If single quotes around the space-separated set of keywords that follow svn:keywords=, as shown in the above example, doesn't work properly on your system for some reason, you might experiment with double quotes, or with leaving off the quote marks. All three forms have appeared in various documentation.)

Setting SVN Keyword Substitution Properties Manually

Otherwise, most subversion clients allow you to manually set keyword substitution properties on a per-file or per-folder basis. Some make it possible for you to set these properties recursively on large numbers of files.

Several representative examples, most of which are untried by the original author of this wiki page:

Remember that, as noted above, files on which keyword substitution properties have been added or changed need to be committed to the Subversion repository, in order for those properties changes to take effect. Only after doing so will you see details regarding this commit and all subsequent commits, such as the last relevant revision number and date, automatically filled in ("expanded") within your source files.

  • No labels

3 Comments

  1. What about javadoc as part of this template? Has there been thought to standards to facilitate automagical generation of API documentation?

    1. Thanks for commenting, Steve. Do you have suggestions for us? We'd welcome them!

      In early 2009, we looked into the Kuali Student approach of generating interfaces and/or documentation from structured Confluence wiki pages. In general, the approach of generating both code and documentation from design docs is still interesting to us.

      After we standardized a number of services on RESTful APIs, we also considered providing API documentation through:

      • Picking up JAX-RS annotations from source files, using a Doclet or similar approach.
      • WADL and similar formal, mostly machine-readable API documentation. (Some JAX-RS frameworks, like Sun's Jersey, can auto-generate WADL.)
      • One or more mechanisms to provide Hypermedia as the Engine of Application State (HATEOAS), essentially providing "self-documenting links" that can be followed by clients in certain of the payloads returned by our services.

      At least at present, however, we've been following the approach of a number of popular providers of RESTful APIs, which is to generate human-readable API documentation, often - as in our case so far - by hand. Clearly, we'd welcome a better approach, to generate documentation faster, with less labor, and with a reduced possibility of transcription errors when going from code to docs. Having machine-readable API documentation would also potentially be a big plus, as it might help facilitate service discovery, code generation, and/or adaptive client requests (in the case of HATEOAS).

      This wiki page has a much more limited scope: to propose a standard comments block for identifying name, purpose, revision status, association with the CollectionSpace project, and copyright for Java class files, which might also be adapted for use with other project artifacts.

  2. Sanjay asked on 2009-07-16:

    Is the following clause not needed?

    "Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License."