1. Welcome to the NSR Physiome Project!
  2. Physiome JSim
  3. The JSim Documentation Set
  4. JSim Source Code Standards

JSim Source Code Standards

This page is for the current JSim version 2.0 and higher. Click here for the earlier JSim 1.6 version.

Introduction

This document describes coding standards for JSim Java source code. It is intended for those contributing Java source code to the JSim CVS archive. JSim is a large program (currently about 80,000 lines), so ensuring some uniformity of appearance is very helpful to those who must read and understand the code.

Since the present author (Erik Butterworth) wrote about 95% of the existing code, the coding conventions described here are I follow. I do not to claim these to be the best of all possible conventions, only that by following these conventions, JSim's code base will be more consistent, and therefore more readable.

This a my first try at this document. It will, no doubt, evolve over time. Sun has done some nice work on Java conventions. I urge readers to consider that document, which is much more complete that this one here. I do differ in some particulars, however. Ultimately, JSim coding conventions will always be some blend of standard conventions and JSim-specific conventions.

JSim Source Code Conventions

General conventions:

  • The ultimate is to produce efficient, readable and maintainable JSim code. Following conventions is only a means to that end. Abandon a convention if it obscures what is going on. Writing clear code is an ongoing problem not amenable to prescriptive solutions. Conventions help somewhat, however.
  • Class names should be of mixed case, starting with a capital. Static final variables should be all caps. Other variables should be mixed case, starting with a non-cap. For example: 
          public class DogHouse {
          public final static int POLLFREQ = 200; //milliseconds
          public DogHouse fleaHotel;   // for Fido
          ...

Format and Indenting

  • Code submitted to the JSim CVS archive should use Unix-style ASCII text files (N/L terminated, no CR).
  • Line width should not exceed 80 characters.
  • Indent the next line after a left-brace. The left-brace itself is placed on the same line as the preceeding statement. Close the brace at the same indentation level as the line of the opening brace.
  • Indent unbraced clauses after if(), while(), for(), etc. unless the entire clause fits easily on a single line.
  • The first indentation is a single tab. Further indentations are four spaces. 8 spaces are assumed to be equivalent to a tab. Set your editor's tab settings to 8 spaces when editing JSim code or it will not be well aligned.
  • Long method bodies (over 50 lines) and highly indented code (e.g. 6 levels) inhibit readability. One solution is to break the code into manageable subroutines. A better one is often to enhance the methods in the classes called.

Comments

  • Double-slash comments are preferred over C-style except for extended multiline comments. This makes it easier to comment out large blocks of code (using C-style comments). javadoc style comments are not used in JSim.
  • Every method should have a preceding comment describing it. Most instance variables should have same-line comments describing them. Long methods should be broken into paragraphs with preceding comments. Comments should appear at least every 10 lines (or so) of a method.
  • Trivial temporary variables (such as integer counters) should NOT be commented. Trivial comments clutter code and reduce readability.

JSim-specific conventions

  • Become familiar with the general purpose utilities available in JSim and reuse (possible enhance) existing ones rather than duplicating code. Especially useful are JSim.util.Util and JSim.util.StringList. User visible numeric formatting should use JSim.util.PrettyFormat.
  • XML parsing is handled via Apache Xerces, and is accessible via PServer.parseXML(). Do not introduce other XML parsers into the system. They are very bulky. XML output can be handled by JSim.data.XMLWriter.
  • If you need a general-purpose language parser, use JLex and CUP, which are already packaged with JSim.
  • JSim packages should contain no more that about 50 class files to be manageable. A directory list of .java files in a package should produce no more than one page of output on a standard terminal. If things are getting too large, consider combining classes, pruning, or making sub-packages.
  • Java source files over 500 lines are difficult to read, and not really needed to meet JSim design requirements. Java class files under 50 lines are usually trivial, unless they are placeholders for future code, or simple extensions to more substantive classes. Ideally readable files hover between 50 and 300 lines.
  • Class names should be chosen unique enough so that they can be called without qualification (e.g. MyClass not JSim.mypackage.MyClass) within the JSim code base.
  • Consult with the programming lead before introducing any third party software into the JSim base to make sure license terms are compatible with JSim's distribution requirements.
  • JSim should run indentically (so far as possible) on all platforms. Java provides mechanisms for doing things (e.g. File names) in a platform independent way. Use them. Avoid native methods and underlying operating system calls except when absolutely necessary.
  • Do not use deprecated methods or classes. Exceptions are made for essential features that are not available elsewhere: Thread.kill() and Sun's embedded java compiler sun.tools.javac.Main.
  • If you are not an NSR employee, a license agreement must be made between your institution and the University of Washington, to allow NSR to distribute your code with JSim. It is not sufficient for you to give your personal agreement. The agreement must be made between institutions.

Comments or Questions?

Give feedback

Model development and archiving support at https://www.imagwiki.nibib.nih.gov/physiome provided by the following grants: NIH U01HL122199 Analyzing the Cardiac Power Grid, 09/15/2015 - 05/31/2020, NIH/NIBIB BE08407 Software Integration, JSim and SBW 6/1/09-5/31/13; NIH/NHLBI T15 HL88516-01 Modeling for Heart, Lung and Blood: From Cell to Organ, 4/1/07-3/31/11; NSF BES-0506477 Adaptive Multi-Scale Model Simulation, 8/15/05-7/31/08; NIH/NHLBI R01 HL073598 Core 3: 3D Imaging and Computer Modeling of the Respiratory Tract, 9/1/04-8/31/09; as well as prior support from NIH/NCRR P41 RR01243 Simulation Resource in Circulatory Mass Transport and Exchange, 12/1/1980-11/30/01 and NIH/NIBIB R01 EB001973 JSim: A Simulation Analysis Platform, 3/1/02-2/28/07.