Each file starts with some header info:
file,
version info,
copyright notice.
Like this:
// $Id: ch07.html 9297 2008-11-30 17:29:00Z linus $
// Copyright (c) 2008 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 file and version is maintained by subversion using keyword substitution.
Remember to set the property "svn:keywords" to "Id" on all source files.
The year in the copyright notice is maintained manually.
This differs from the Sun Code Conventions that
requires the initial comment to be a C-style comment.
This is checked by Checkstyle.
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$", 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)!
