8/13/2019 javaCodingStandardsSummary.pdf

1/2

Always use (a few exceptions discussedbelow) full English descriptors. Use lowercase letters in general, but capitalize thefirst letter of class / interface names and

the first letter of any non-initial word

Use terminology applicable to the domainUse mixed case for readability

Use short forms sparingly and intelligentlyAvoid long names (< 15 characters)

Avoid names that are similar ordiffer only in case

A gooddeveloper knows thatthere is more to development

than programming.A greatdeveloper knows thatthere is more to development

than development.

Full English description of value/object beingpassed, possibly prefixing the name with aor an.

Full English description, 1st letter lowercase,1st letter of any non-initial word in uppercase

Pefixed with

is

Full English description, with the first lettersof all words capitalized

Name of class/interface; if > 1 class in file, prefixedwith .javato indicate it's a source code file.

Full English description describing usage; typeof the component concatenated onto the end.

Use the name of the class

Will invoke finalize() member function beforean object is garbage collected

It is generally accepted to use the letter eto represent exceptions

Uppercase letters, words separated by under-scores. Better: final static getter member functions

Prefix the name of the field being accessedwith get

Full English descr. concept of interface, 1st lettersof words cap'd. Postfix name with able, ible, or er

Full English description, 1st letter in lowercase but do not hide existing fields/fields

It is generally accepted to use the letters i , j, or k , or the name counter .

See Classes - Global packages: reverse nameof Internet domain & postfix the package name.

Full English description of what it does startingwith active verb if possible, 1st letter in lower case

Prefix the name of the field being accessedwith set

Arguments/parameters

customer , account , - or- aCustomer , anAccount

Fields / properties firstName , lastName ,warpSpeed

Boolean gettermember functions isPersistent() , isString(), isCharacter()

Classes Customer ,SavingsAccount

Compilation unitfiles

SavingsAccount.java ,Singleton.java

Components /widgets

okButton , customerList ,fileMenu

Contructors Customer() ,SavingsAccount()

Destructors finalize()

Exceptions e

Final Static fields/ constants

MIN_BALANCE ,DEFAULT_DATE

Getter memberfunctions

getFirstName() ,getWarpSpeed()

Interfaces Runnable , Prompter ,Singleton

Local variables grandTotal , customer ,newAccount

Loop counters i , j , k , counter

Package ca.uvic.neptune.per-sistence.mapping

Member Functions openFile() , addAccount()

Setter memberfunctions

setLastName() ,setWarpSpeed()

Item Example Naming convention

When you go against a standard,document it. All standards, except for

this one, can be broken. You must

document why you broke thestandard, the potential implicationsof breaking the standard, and anyconditions that may/must occur

before the standard can be applied tothis situation.

JAVA NAMINGCONVENTIONS

General Concepts

8/13/2019 javaCodingStandardsSummary.pdf

2/2

Rule of thumb: if youve never seen thecode before, what documentation would

you need to quickly understand it

Documentation

Immediately before declarations

of interfaces, classes, memberfunctions and fields to documentthem. These are processed by

javadoc to create externaldocumentation for a class.

/**

Customer A customer is anyperson or organization that wesell services and products to.@author S.W. Ambler*/

C Style C-style comments to disablelines of code that are no longerapplicable, but that you want tokeep just in case ~ or whiledebugging.

/*Commented out by J.T. Kirk on 1/1/03replaced by preceding code. Deleteafter 2 years if still not applicable. . . (the source code )*/

Single line Use single line commentsinternally within memberfunctions to document businesslogic, code sections anddeclarations of temporary

variables.

// Apply a 5% discount to all// invoices over $1000 as defined by// the Sarek generosity campaign// started in Feb 1995

Comments should add to clarityIf it isnt worth documenting,

it isnt worth runningNo decoration / banner-like comments

Keep comments simpleWrite documentation beforewriting code

Why ~ not What

Arguments / parameters

Fields/properties

Classes

Compilation units

Getter member functionInterfaces

Local variablesMember Functions

(Documentation)

Member Functions(Internal comments)

Package

The type of the parameterWhat it should be used forAny restrictions or preconditionsExamplesIts descriptionDocument all applicable invariantsExamplesConcurrency issuesVisibility decisionsThe purpose of the classKnown bugsThe development/maintenance history of the classDocument applicable invariantsThe concurrency strategyEach class/interface defined in the class, incl. a brief descriptionThe file name and/or identifying informationCopyright informationDocument why lazy initialization was used, if applicableThe purposeHow it should and shouldnt be usedIts use/purposeWhat and why the member function does what it doesWhat a member function must be passed as parametersWhat a member function returnsKnown bugsAny exceptions that a member function throwsVisibility decisionsHow a member function changes the objectInclude a history of any code changesExamples of how to invoke the member function if appropriateApplicable preconditions and postconditionsDocument all concurrencyControl structuresWhy, as well as what, the code does

Local variablesDifficult or complex codeThe processing orderThe rationale for the packageThe classes in the package

Java comment types

WHAT todocument

Your code must beunderstandable to others

Accessor member functions

Fields

Classes

Local variables

Member functions

Consider using lazy initialization for fields in the database

Use accessors for obtaining and modifying all fieldsUse accessors for constants

For collections, add member functions to insert and

remove items

Whenever possible, make accessors protected, not public

Fields should always be declared private

Do not directly access fields, instead use accessor

member functions

Do not use final static fields (constants), instead use

accessor member functions

Do not hide names

Always initialize static fields

Minimize the public and protected interfaces

Define the public interface for a class before you begin

coding it

Declare the fields and member functions of a class in the

following order:

constructors

finalize()

public member functions

protected member functions

private member functions

private field

Do not hide names

Declare one local variable per line of codeDocument local variables with an endline comment

Declare local variables immediately before their use

Use local variables for one thing only

Document your code

Paragraph your code

Use whitespace, one line before control structures and two

before member function

declarations

A member function should be understandable in less than

thirty seconds

Write short, single command lines

Restrict the visibility of a member function as much as

possible

Specify the order of operations

This text is a summary ofScott Ambler's 'WritingRobust Java Code'

The AmbySoft Inc.Coding Standards for

Java - v17.01d

This layout by Maike Dulk

JAVA DOCUMENTATIONCONVENTIONS

General ConceptsJAVA CODINGCONVENTIONS

99.9% of the time it is more importantto program for your fellow

developers than for the machine