argouml-tigris-org.github.io

Web pages for the ArgoUML project.

From the ArgoUML wiki at argouml.tigris.org.
Wiki: When Writing Java Code

Standards for writing Java Code in the ArgoUML project

The coding style for ArgoUML is based on the Code Conventions for the Java Programming Language. The exceptions and some comments are described here.

License

Every source file starts with a License text. Two different license texts are used:

  • New files - the EPL License text together with the list of Copyright holders.
  • Old files that are updated - the EPL License text with the list of Copyright holders followed by the BSD file.

See the detailed discussion about the License.

New files

Each file starts with some header info: file, version info, copyright notice. Like this: 

/* $Id$
 *******************************************************************************
 * Copyright (c) 2009-2010 Contributors - see below
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Linus Tolke - <optional description of the contribution>
 *    Bob Tarling
 *******************************************************************************
 */

package whatever;

Old files that are updated

Each file starts with some header info: file, version info, copyright notice. Like this: 

/* $Id$
 *******************************************************************************
 * Copyright (c) 2009-2010 Contributors - see below
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Linus Tolke - <optional description of the contribution>
 *    Bob Tarling
 *******************************************************************************
 *
 * Some portions of this file was previously release using the BSD License:
 */

// Copyright (c) 2000-2007 The Regents of the University of California. All
// Rights Reserved. Permission to use, copy, modify, and distribute this
// software and its documentation without fee, and without a written
// agreement is hereby granted, provided that the above copyright notice
// and this paragraph appear in all copies.  This software program and
// documentation are copyrighted by The Regents of the University of
// California. The software program and documentation are supplied "AS
// IS", without any accompanying services from The Regents. The Regents
// does not warrant that the operation of the program will be
// uninterrupted or error-free. The end-user understands that the program
// was developed for research purposes and is advised not to rely
// exclusively on the program for any reason.  IN NO EVENT SHALL THE
// UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
// SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS,
// ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
// THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF
// SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY
// WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
// MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
// PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
// CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT,
// UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

package whatever;
...

The BSD License part of the license differs from the Sun Code Conventions that requires the initial comment to be a C-style comment.

Details on the license header

The list of Contributors is maintained manually. Add your name when you are adding a contribution.

The file, revision, date and last committer is maintained by subversion using keyword substitution. Remember to set the property "svn:keywords" to "Author Date Id Revision" on all source files. The year in the first copyright notice is maintained manually. For the BSD license part, it is not changed.

This first part of this (up to the Contributors: of the EPL header) will be checked by Checkstyle.

Conventions

  • All instance variables are private.
  • This is not required by the Sun Code Conventions but an additional requirement for ArgoUML.
  • This is checked by Checkstyle.
  • Use Javadoc for each class, instance variable, and methods that are not overriding or implementing a method from an interface or extended class. In general do not put comments in the body of a method. If you are doing something complex enough to need a comment, consider breaking it out into its own private commented method.
  • If you are overriding or implementing a method and you want to describe specifics of the implementation, use the Javadoc and reference the overridden or implemented method.
  • This is not required by the Sun Code Conventions but an additional requirement for ArgoUML.
  • This is partly checked by Checkstyle. Checkstyle does currently only warn if a Javadoc comment is omitted for public, protected or default visibility variables.

  • Indicate places of future modifications with 

          // TODO: reason and explanation

    or if within a Javadoc or c-style comment 

          * TODO: reason and explanation
  • This differs from the Sun Code Conventions that uses either XXX or FIXME depending on if it works or not.
  • This is partly checked by Checkstyle. Checkstyle does currently allow "TODO " (without the colon).
  • Four spaces should be used as the unit of indentation. Tabs must be set exactly every 8 spaces (not 4) and represent 2 indents.
  • This is exactly as it is stated in the Sun Code Conventions. It is here just for emphasis.
  • This is checked by Checkstyle.
  • If possible use lines shorter than 80 characters wide.
  • This is exactly as it is stated in the Sun Code Conventions. It is here just for the emphasis.

  • This is checked by Checkstyle. Checkstyle ignores three kinds of lines in this check because of the historical use of long class names and package names. These are lines that contain "@see some method name", "// $Id:whatever$", "/* $Id:whatever$", and import statements.

  • Open brace on same line (at end). Both for if/while/for and for class and functions definitions.
  • This is exactly as it is stated in the Sun Code Conventions. It is here just for the emphasis.
  • Always use braces i.e. for all if/while/for definitions.
  • Use deprecation when removing public and protected classes, methods and attributes.
  • Whenever you have a public or protected method or attribute in a class or a public class that you want to remove, rename, move to a different package, change the signature in an incompatible way, or reduce the visibility for you shall always deprecate it first. After the next stable release you (or someone else) can remove it.
  • In the future, when the subsystems are well defined and it is clear what public or protected methods, attributes or classes that are part of a certain subsystem's exported interface we can allow an exception to this rule for methods, attributes and classes that are not. (See Section 4.2, “Relationship of the subsystems”.)
  • Write deprecation statements like this: 
  •            * @deprecated by your name in the upcoming release. Use {@link whatever}
           *             a complete explanation on what to do instead
  • This is not checked by Checkstyle.

  • Rationale: This is part of the "Do Simple Things"-development approach that we use in ArgoUML. ArgoUML is a big project with lots of legacy code that we do not know exactly how it works. Deprecation shows the intent between decision to remove a method and the point where it is actually removed and this without breaking anything of the old code. There are also modules or plug ins that we might know nothing about that could be loaded by some user to run within ArgoUML to add functionality. It is for the modules and plug ins that we always save deprecated methods to the next stable release. It makes it possible for the module developers to do work during the unstable releases and release at the same time as ArgoUML releases its stable release. Failing to maintain API stability will discourage developers from creating new modules for ArgoUML.

  • Don't use deprecated methods or classes.

  • Rationale: Deprecation is an indication that a class is to be removed. We always want to build ArgoUML in a way that allows for future updates of everything. Using things that are on the way out already when doing the implementation is for this reason not allowed.

  • Rationale 2: If you feel like you really want to use a method that is deprecated instead of the replacement you should first convince the person responsible for doing the deprecation that he has made a mistake and upgrade ArgoUML to a version of that library without that method or class deprecated. If it is within ArgoUML discuss it with the person who actually did the deprecation or in the development team.

  • Comment: There is an ongoing task (probably perpetually) to change the calls to deprecated methods and classes that have been deprecated after use in ArgoUML. This is a normal part of improving ArgoUML. If this work is too slow it makes it impossible to upgrade to new versions of different sub-tools. This problem is seen by "the person responsible for sourcing of the sub-tool" when actually trying to upgrade the sub-tool. (See Section 9.6, “How to relate issues to problems in dependencies”.)
  • Don't use very long package and class names.
  • To make the code readable, keep class names shorter than 25 chars, and have at most four levels of packages.

  • Historically in the ArgoUML design, a deep package structure was used. There are several places in the code where the package structure is mimicking the UML hierarchy of objects resulting in impossibly long package names like org.argouml.model.uml.behavioralelements.collaborations.class name, and org.argouml.uml.ui.behavior.common_behavior.class name.

  • While establishing the subsystems we use a two-level approach much like the rest of the Java world. For the subsystem API we always use: org.argouml.subsystem package name i.e. the classes are in the subsystem's directory and all subsystems have package names that is a single level below org.argouml. If a subsystem is really complex or will be complex w.r.t. the amount of classes (meaning more than 50 files with classes), we create new packages with internal classes on a single level below the subsystem package.
  • This is the plan for the subsystems and new classes. Don't move old classes just yet! That would create more confusion that it would help.
  • For everything else follow Code Conventions for the Java Programming Language (called Sun Code Conventions)!

Some of these rules are marked with a comment that they are checked by a Checkstyle. Checkstyle is a tool available with the ArgoUML development environment preconfigured for these rules. The current configuration can be found in argouml/tools/checkstyle/checkstyle5_argouml.xml (and argouml/tools/checkstyle/checkstyle_argouml.xml for previous versions of Checkstyle).

Look at the result of the Continuous Integration server to see the found checkstyle problems.

Checkstyle will also check some of the rules from the Sun Code Conventions that are not stated here. Furthermore Checkstyle enforces the order of modifiers to conform to the suggestions in the Java Language Specification, Section 8.1.1, 8.3.1, 8.4.3.

CategoryFromCookbook

When Writing Java Code (last edited 2011-08-10 22:35:56 -0700 by linus)