Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Coding Conventions

The VM_prefix

By convention, any class which should be loaded into the boot image starts its name with VM_. This is used by the build configurator,jconfigure, which uses that information to create $RVM_BUILD/RVM.primordials, the file containing the list of classes that should be written into Jikes RVM's boot image.

The MMTk classes don't follow this naming convention because they're an independent subsystem, but the rest of Jikes RVM does.

Assertions

Partly for historical reasons, we use our own built-in assertion facility rather than the one that appeared in Sun®'s JDK 1.4. All assertion checks have one of the two forms: if (VM.VerifyAssertions) VM._assert( condition
if (VM.VerifyAssertions) VM._assert( condition, message)
VM.VerifyAssertions is a public static final field. The RVM_WITHOUT_ASSERTIONSconfiguration variable determines VM.VerifyAssertions' value. If RVM_WITHOUT_ASSERTIONS is enabled, Jikes RVM has no assertion overhead.
If you use the form without a message, then the default message "vm internal error at:" will appear.

If you use the form with a message the message must be a single string literal. Doing string appends in assertions can be a source of horrible performance problems when assertions are enabled (ie most development builds). If you want to provide a more detailed error message when the assertion fails, then you must use the following coding pattern: if (VM.VerifyAssertions && condition) VM._assert(false, message);
An assertion failure is always followed by a stack dump.

Coding Style Introduction

Regrettably, much code in the current system does not follow any consistent coding style. This is an unfortunate residuum of the system's evolution. It makes editing sometimes unpleasant, and prevents Javadoc from formatting comments in many files. To alleviate this problem, we present this style guide for new Java™ code; it's just a small tweak of Sun®'s style guide.

File Headers

Every file needs to have a header with a copyright notice and one or more @author tags. There may additionally be a @modified tag for someone who modified code but doesn't want to claim co-authorship. (@modified is our own extended tag.)

A Java example of the notices follows.

Example.java

Coding style description

The Jikes™ RVM coding style guidelines are defined with reference to the Sun® Microsystems "Code Conventions for the Java™ Programming Language", with a few exceptions listed below. Most of the style guide is intuitive; however, please read through the document (or at least look at its sample code).

We have adopted four modifications to the Sun code conventions:

  1. Two-space indenting The Sun coding convention suggests 4 space indenting; however with 80-column lines and four-space indenting, there is very little room left for code. Thus, we recommend using 2 space indenting. There is to be no tabs in the source files.
  2. 132 column lines in exceptional cases The Sun coding convention is that lines be no longer than 80 columns. Several Jikes RVM contributors have found this constraining. Therefore, we allow 132 column lines for exceptional cases, such as to avoid bad line breaks.
  3. if (VM.VerifyAssertions) As a special case, the condition if (VM.VerifyAssertions) is usually immediately followed by the call to VM._assert(), with a single space substituting for the normal newline-and-indentation. There's an example elsewhere in this document.
  4. Capitalized fields Under the Sun coding conventions, and as specified in The Java Language Specification, Second Edition, the names of fields begin with a lowercase letter. (The only exception they give is for some final static constants, which have names ALL_IN_CAPITAL_LETTERS, with underscores separating them.) That convention reserves IdentifiersBeginningWithACapitalLetterFollowedByMixedCase for the names of classes and interfaces. However, most of the final fields in the VM_Configuration class and the VM_Properties interface also are in that format. Since the VM class inherits fields from both VM_Properties and VM_Configuration, that's how we get VM.VerifyAssertions, etc.

Javadoc requirements

All files should contain descriptive comments in Javadoc™ form so that documentation can be generated automatically. Of course, additional non-Javadoc source code comments should appear as appropriate.

  1. All classes and methods should have a block comment describing them
  2. All methods contain a short description of their arguments (using @param), the return value (using @return) and the exceptions they may throw (using @throws).
  3. Each class should include @see and @link references as appropriate.
  • No labels