You are on page 1of 21

A Naming Convention for Java Program Identifiers

August 6, 1998

I. Lee Campbell for Client, Inc.

2Java Identifier Naming Convention Copyright 1998, Edward Lee Campbell .

All Rights Reserved. No part of the contents of this publication may be reproduced or transmitted in any form or by any means without the written permission of the author excepting only usage under the Fair Use Doctrine. The information in this document is subject to change without notice This document is a derivative work based on previous published and unpublished works of Edward Lee Campbell.

1998 Edward Lee Campbell. All Rights Reserved

Java Identifier Naming Convention

Contents
A NAMING CONVENTION ........................................................................................................................1 FOR .................................................................................................................................................................1 JAVA PROGRAM IDENTIFIERS...............................................................................................................1 AUGUST 6, 1998.............................................................................................................................................1 I. LEE CAMPBELL.......................................................................................................................................1 FOR..................................................................................................................................................................1 CLIENT, INC..................................................................................................................................................1 INTRODUCTION..........................................................................................................................................6 OVERVIEW.......................................................................................................................................................6 GOAL OF THIS CONVENTION...............................................................................................................................6 INTENDED AUDIENCE.........................................................................................................................................6 DOCUMENT ORGANIZATION................................................................................................................................6 ASSUMPTIONS...................................................................................................................................................7 METHODS........................................................................................................................................................7 MEASUREMENTS................................................................................................................................................7 SCOPE.............................................................................................................................................................8 SYMBOL NAMING CONVENTIONS........................................................................................................9 THE SOLUTION NAME DOMAIN...........................................................................................................................9 TYPED IDENTIFIER NAMING................................................................................................................................9 A JAVA NAMING CONVENTION...........................................................................................................12 LIMITATIONS..................................................................................................................................................12 CLASSES........................................................................................................................................................12 CONSTANTS ...................................................................................................................................................12 PROPERTIES AND VARIABLES............................................................................................................................12 PROPERTY ACCESS METHODS...........................................................................................................................13 METHODS......................................................................................................................................................13 EVENTS.........................................................................................................................................................14 JAVA IDENTIFIER NAMING CONVENTION REFERENCE.............................................................15 BASE MODIFIERS............................................................................................................................................15 BASE TYPES...................................................................................................................................................15 SPECIAL TYPES...............................................................................................................................................15 QUALIFIERS....................................................................................................................................................16 AWT Qualifier Abbreviations.................................................................................................................16 AWT Standard Qualifiers.......................................................................................................................19 APPENDIX A................................................................................................................................................20 RULES FOR ABBREVIATING SYMBOLS.................................................................................................................20 BIBLIOGRAPHY.........................................................................................................................................21 JAVA.............................................................................................................................................................21 OBJECT ORIENTED SOFTWARE DEVELOPMENT.....................................................................................................21

4Java Identifier Naming Convention

SOFTWARE DEVELOPMENT................................................................................................................................21

1998 Edward Lee Campbell. All Rights Reserved

Java Identifier Naming Convention

Change History
Change 0.1 0.2 0.3 Date 3/19/1998 4/1/1998 8/6/98 Author TC TC TC Description Java version Initial rewrite and revision for JDK 1.1 and JBuilder 2 beta Jbuilder 2 update

6Java Identifier Naming Convention

Introduction
This is a naming convention for forming program identifiers in Java source code. Program identifiers include class, method, property, event, and variable names. This document defines the software naming convention that applies to the ODDS project development effort.

Overview
This document specifies a computer software naming convention for use in projects being developed in the Delphi Integrated Development Environment and Object Pascal languages as defined by Borland International for Delphi 2, 3, and 4. This convention is meant to be compatible with the Javasoft Code Convention. This naming convention is based on three things: assumptions about the nature of software development, guidelines for managing program name domains, and measurements to gauge the effectiveness of a naming convention.

Goal of This Convention


The goal of this convention is better management of program source code complexity. Achieving this goal relies primarily on reducing the total number of names (objects, properties and methods) that must be devised to express a simple, consistent and extensible program solution domain, a solution language. Stated another way: making simple, understandable, and consistent names for software classes, constants, variables, functions, and objects across the ODDS project development effort is the goal of this convention. This convention is a primary element of formal development methods for coding in the Java language.

Intended Audience
All Developers and Technical Writers for any project which requires or allows the use of this naming convention.

Document Organization
The organization of this document anticipates at least one sequential reading. It is also arranged to be useful as a reference.

1998 Edward Lee Campbell. All Rights Reserved

Java Identifier Naming Convention

Basis
This naming convention is based on three things: assertions about the nature of software development, selected methods of managing program name domains, and measurements to gauge the effectiveness of a naming convention.

Assumptions
The General Principle of Software Quality is that improving quality reduces development costs. Understanding this principle depends on understanding a key observation: The best way to improve productivity and quality is to reduce the time spent reworking code, whether the rework is from changes in requirements, changes in design, or debugging. (McConnell, Code Complete, p567). Consider for a moment all the names we may need just to identify a single object: we have the name of the object itself, the name of its class, and the name of the module in which that class is declared. Multiply this by thousands of objects and possibly hundreds of classes, and you have a very real problem. (Booch, Object Oriented Analysis and Design, p164) A few projects - for example the space shuttle software - have achieved a level of 0 defects in 500,000 lines of code using a system of formal development methods, peer reviews, and statistical testing. (McConnell, Code Complete p 611) In pursuit of higher software quality, lower development costs, and zero defects the following assertions are made: A Naming Convention is an effective tool in managing the domain of names needed to express a software solution. A Naming Convention is an essential part of software quality A Naming Convention is an essential part of managing complexity A Naming Convention is an essential part of formal software development methods Adherence to this naming convention will result in clearer, simpler, more consistent source code across all source modules of the project. Adherence to this naming convention will reduce the learning curve of all subsequent developers who work on this project. Additional measures of reduced complexity are available using commercial source code analysis tools.

Methods
The requirements in this document are based on standards, methods, and techniques defined in the following published texts: Booch, Grady 1994. "Object-Oriented Analysis and Design with Applications", 2nd ed. byRedwood City, CA: Benjamin/Cummings. Maguire, Steve 1994. "Debugging the Development Process". Redmond WA: Microsoft Press. Maguire, Steve 199x. "Writing Solid Code. Redmond WA: Microsoft Press. McConnell, Steve 1993. "Code Complete, A Practical Handbook of Software Construction". Redmond WA: Microsoft Press. Additional sources of information can be found in the Bibliography.

Measurements
A successfully drawn Naming Convention will produce measurable results of the following types Simpler source code More consistent source code

8Java Identifier Naming Convention Simplified program symbol creation. Fewer compile time errors Fewer unique basic object names than source code developed without a Naming Convention. Some measurements of success are subjective others can be measured with source code analysis tools.

Scope
While the techniques and practices defined herein are intended to be consistent with LUCENT TECHNOLOGIES, Standards Policy, this document was developed to accommodate the specific requirements of the ODDS project and supersedes all other standards. When release 1.0 is finalized and distributed, this standard will be frozen. Changes to this convention subsequent to the first release are at the discretion of the Program Manager. It is the responsibility of the advocate of any approved change to update this document with the approved change, enter an appropriate summary into the Change History section above, and redistribute this document to all team members. This convention does not include: A complete Coding Standard A description of design methodology A design for the ODDS project.

1998 Edward Lee Campbell. All Rights Reserved

Java Identifier Naming Convention

Symbol Naming Conventions


This section is concerned with describing a convention for program symbols that will: Simplify the creation of program symbols, Result in more consistent source code Require up to an order of magnitude fewer base symbol names in the completed system, making it far more understandable and maintainable. Increase developer productivity Decrease learning curve for subsequent developers

Symbol naming conventions are a means of managing complexity in programs by reducing the total number of symbol names that must be devised to express a solution. The actual mechanics of a naming convention can help avoid errors at the earliest possible time, make source files simpler and easier for others to read, and reduce compile time errors.

The Solution Name Domain


This is the intersection of design and implementation. It is where the language of the solution is specified: the nouns, verbs, and external entities (properties, methods, and events) that express the essential characteristics of the problem, the solution, and its implementation. A Naming Convention can not substitute for a well thought out design. It is the system design that defines most of the basic components of the solution language. It is the naming convention that attempts to bring simplicity, consistency, and extensibility to the solution language. Devising the name domain of a software solution is an essential activity of program design, but beyond the scope of this document. By this I mean that most of the basic objects, properties, methods, and events will have been specified in the top level program design. Here we are concerned with implementation and a few simple rules, which if applied to the design name space, will have a disproportionate effect on the overall complexity of the final software system. Achieving this result requires a simple but complete regimen: 1. Review the designed solution name domain for simplicity and consistency. 2. Reduce the set of method, property and event names required by the design by adopting common names where possible. 3. 4. Define the set of common names in the design and corresponding abbreviations Abbreviate consistently, see appendix A for a sample abbreviation guide.

Typed Identifier Naming


Given that the set of basic program objects has been defined, naming different aspects and uses of these objects can be simplified by extending the basic set of objects with prefixes and suffixes. This standard encourages but does not require the use of a naming convention called Type Prefix Naming. This naming convention has as its origin the original Microsoft Windows project coding standards. Charles Simonyi is credited with devising an early version of this convention known as Hungarian naming. The value of type prefix naming is better name space management and reduction of complexity in program development. Using this technique also tends to reduce conversion errors in assignment statements before compile time. These benefits come as a direct result of reducing the number of original names that each module must contain and by making type mismatches in assignment statements more obvious. //*** simplify this The algorithm for devising a type prefix symbol name is not complex:

10Java Identifier Naming Convention 1. 2. Devise or choose an appropriate solution vocabulary noun to name this program object, e.g. ClientAccount. Construct a prefix for the symbol which is either the symbols base type (primitive data type abbreviation) or parent class name and optional modifier, e.g. aClientAccount (array of Client Accounts), lClientAccountID (long Client Account IDentifier)

10

3.

If the symbol is a method that takes parameters, construct a suffix to identify the primitive data type(s) or parent class(es) passed, possibly concatenated with a preposition (By, From, Of), e.g. aClientAccountOfProject(Project), lClientAccountIDFromNameStr(NameStr). Optionally add a qualifier suffix to further identify the symbol name and its use. Qualifiers suffixes are abbreviations of common programming entities and classes of the language Component Libraries, e.g. aClientAccountNameListBox, //*** Optionally add a global use qualifier prefix to further identify the symbol name and its use. Qualifier prefixes are abbreviations of common algorithm global attributes: Current, Previous, Next, Maximum, Minimum, Average, Total, etc. For example: MaxClientAccountBalance, CurrentClientAccountFromLogon(Logon);

4.

5.

Graphically this process can be represented as: [modifer] + [base type] + [Attribute QUALIFIER] + [Name] + [QUALIFIER] Suppose, for example, the naming convention consisted of the following sets of modifiers, format types, and qualifiers: Base Modifiers a Base Types b by c cl i l s sf AWT Qualifiers Btn ChB DT Edit LsB Normal Programming Entities Buf Len Log Num Sys Tel Button CheckBox DateTime Edit ListBox Buffer Length Log Number of an element in a series System a PSTN Telephone access number boolean byte char class int long static, class static final array of

Using the lists above, the data type and/or library object ancestor of the following program entities are readily apparent: //*** insert class example

1998 Edward Lee Campbell. All Rights Reserved

10

Java Identifier Naming Convention

11

As the example shows, this technique makes it possible to limit the number of new symbol names needed. Type-prefixed names are made unique by their prefixes. With experience, it becomes easy to use the same name with a different prefix to name different attributes of the same solution object. A specific example is an array of bytes comprising program communications buffer, the base record is named abComBuf. Easily named associated properties of this record can be derived as follows: //*** replace this example clComBuf iComBufLen, a class describing a communications buffer an int representing the length of ComBuf

In this way type prefix naming helps eliminate type mismatches in assignment statements and reduces complexity by reducing the number of symbol names that must be devised. For a complete list of base types and modifiers see Section titled Java Identifier Naming Convention Reference below.

12Java Identifier Naming Convention

12

A Java Naming Convention


The complete definition of the Java Naming Convention is contained in this section.

Limitations
Global Object names, their public methods, and published properties are exempted. With the concurrence of management, this convention is voluntary.

Classes
Rules Object names should be based on nouns from the solution name domain or the solution class from which the object is derived. To this is added a qualifier identifying the object's program use. Class method names are formed by the same rules as procedures and functions below, except: 1. 2. 3. Notes: Base class names are drawn from the system solution name domain Base class name qualifiers are drawn from the installed Component Library and other installed components Base class name qualifiers are drawn from abbreviations of common programming entities. Classes should explicitly define constructors that take no arguments. Examples: //*** insert class example Private method names are modified by two leading underscores __. Protected method names are modified by a single leading underscore _. Public method names are not type prefixed.

Class property names are not prefixed

Constants
Rules: Constants which do not change value during program execution should be entered in all upper case (excepting type prefixes) with underscores separating words. Unless compelling reasons exist, make class instance names the same as or an abbreviation of the class with a qualifier. Notes: The prefixes: s and scl are equivalent and refer to a static class entity. The prefixes: sfand sfnl are equivalent and refer to a static final class entity. Examples: //*** insert examples of statics and static final constants

Properties and Variables


Rules: Form names for properties, variables, and arrays by the following algorithm: [modifer] + [basetype] + [Variablename] + [QUALIFIER] OR

1998 Edward Lee Campbell. All Rights Reserved

12

Java Identifier Naming Convention [modifer] + [basetype] + [QUALIFIER] + [Variablename] where: bracketed items are optional with the exception that one of: [basetype] or [Variablename] or [QUALIFIER] MUST be present The first non prefix letter of the variable name is CAPITALIZED or preceded by an underscore. All non integer (int) variables begin with a lower case letter which is either a base type, or a modifier and base type. Notes:

13

Property names do not begin with verbs Variable names consisting of only a base type or a modifier and base type are generic data types for local use and limited scope. e.g. i : integer; l : long; Str : String; A qualifier that represents a calculated characteristic of the symbol, should be placed it at the end of the symbol name, e.g. SalesAvg; DiscountMin; SalesAmt. A qualifier that represents a global class of data such as a program or subsystem wide characteristic such as Minimum or Maximum should be placed first, e.g. "MinAmpsReq" (Minimum Amperes Required) or "MaxTempF" (Maximum Temperature Fahrenheit)

Property Access Methods


Rules: Form names for property access methods by the following algorithms. Getting a property value: [get] + PropertyName Setting a property value: [set] + PropertyName Notes: The use of get and set is optional. Examples: CurPropNameValue = Object.getPropNameValue(); setPropNameValue(NewValue); CurPropValue = Object.PropName(); ObjectPropName(NewValue); //traditional procedural technique //simpler object oriented technique

Methods
Rules: Form names for function and procedure names by the following algorithm: [modifer] + [basetype_of_return_value] + Function_name + [From, Of, By] + [ParameterType] where bracketed items are optional for public functions Methods that return no value are not prefixed or may be prefixed with a v. The first non prefix letter of the function or procedure name is CAPITALIZED or preceded by an underscore.

14Java Identifier Naming Convention

14

All functions returning a primitive data type and procedures begin with a lower case letter which is either a base type, or a modifier. All functions returning an object reference begin with o or the name of the class that defines the reference. All functions returning a boolean value are prefixed with b or begin with an intransitive verb denoting a state of being, e.g. Is, Has, Can. Notes: Library functions should be grouped according to logical function and have a shortcapitalized prefix identifying the library. Function names formed of a verb and object noun have been used with success, e.g. UpdateSysinfo(clSysinfo SysInfo); Function names formed of a return type, operation and source noun have been used with success, e.g. ConferenceOfCustomerID, bValidCustomerPassword. Function names formed of data types separated by a verb/operation have been used with success, e.g. StrToInt(s : string); DateTimeToStr(dt : TDATETIME) Functions and procedures which operate on data objects of global or multifile scope should have the object name appended, e.g. XYFromSysWindow(); If the function name begins with an intransitive verb the return value is evaluated as boolean (true or false) and the base type "b" is omitted by convention, e.g. IsRegistered;

Events
Rules: Form names by On + EventName + [Parmtype] //***

1998 Edward Lee Campbell. All Rights Reserved

14

Java Identifier Naming Convention

15

Java Identifier Naming Convention Reference


This section contains the complete Type-Prefix Naming convention elements for Object Pascal language used in programming Pascal and Delphi applications.

Base Modifiers
_ __ //*** //*** a fnl na o s sync tr v vo protected private array of final native object of static synchronized transient void volatile

Base Types
b by c cl dd f i l sh boolean byte char class, user defined double floating point integer long short int

Special Types
A ASC C I Abstract Abstract Super Class Class, alt Interface, COM, OLE, ActiveX

16Java Identifier Naming Convention

16

Qualifiers
This section contains the Type-Prefix Naming convention elements for Delphi Visual Component Library objects used in programming Delphi applications based on the following general abbreviated base types. This is version 2.1 10/7/96 of this convention.

AWT Qualifier Abbreviations


primitive wrappers Array Byte Bool Buf Char Dbl Float Int Long Sh Str StrBuf Array Byte Boolean Buffer Character Double Float Integer Long Short String String Buffer

Other AWT Object Abbreviations er,or r ed d Anmr B Bar Bfrd Btn Canvas Choice Chart ChB Chsr CmB Col Comp Count Ctrl Ctnr D DB, Db Dlg Edit Edtr Evt Exc Field File Float Font Gr GrB Animator prefix Bevel, Border, BPnl, suffix Box Bar Buffered Button Canvas Choice Chart CheckBox Chooser ComboBox Column Component Count Control Container Data DataBase Dialog Edit Editor Event Exception Field File Float, real Font Graphic GroupBox

1998 Edward Lee Campbell. All Rights Reserved

16

Java Identifier Naming Convention Grid Grp Horz Img Item Itr Lbl List Locr LView Lkp LsB M Memo Menu Nav, Navg NtBk Open Otl Paint Parm Peer Plyr Pkg Pnl Prn Proc Prop Prgr Pup Qry R RBtn Rdr RGrp Rpt Rslvr Scrl Sepr Set Shape, Shp Spd Spltr Src Stat Str StrBuf Strm SProc Svc Srvr Tab Tabd Tbl Thr Tm Grid Group Horizontal Image Item Iterator label List Locater ListView Lookup ListBox Menu Memo Menu Navigator NoteBook Open Outline Paint Parameter Peer Player Package Panel Print Procedure Property Progress Popup Query Radio Radio button Reader Radio group Report Resolver Scroll Separator Set Shape Speed Splitter Source, DSet, DSrc Status String StringBuffer Stream Stored Procedure Service Server Tab Tabbed Table Thread Time

17

18Java Identifier Naming Convention Tmr Tree TView Tx TxField Wtr Vert Xpar, Timer Tree Tree View Text TextField Writer Vertical Transparent

18

1998 Edward Lee Campbell. All Rights Reserved

18

Java Identifier Naming Convention

19

AWT Standard Qualifiers


Abbreviations of standard classes: //*** insert objects from VCafe, JBuilder, VJ ides

20Java Identifier Naming Convention

20

Appendix A Rules for Abbreviating Symbols


Rules Where a symbol is an abbreviation of a single word for which there is no common abbreviation, abbreviate the word by one of the following methods: 1. Use the first three letters of the word: e.g. Cur for current Ins for insert 2. Use the first three consonants of the word: e.g. Bgn for beginning Cnf for configuration 3. Use an intuitive mnemonic abbreviation e.g. Info for Information Cfg for Configuration Spell the symbol omitting vowels e.g. Btn for button Grp for Group Pnl for Panel Lbl for Label 5 Words ending in ed add d eg tabd for tabbed 6 Words ending in er add r e.g. sepr for separator, itr for iterator

4.

Notes DO NOT use abbreviations which differ from their full spelling by one letter. It has proven difficult to remember which letter is omitted. e.g. DO NOT USE: Opn for open DO NOT USE: Dat for data DO NOT USE: Loc for lock DO NOT USE: Nam for name Where a symbol is an abbreviation for a phrase, each letter associated with the beginning of a word in the phrase is CAPITALIZED. e.g. DbF == Database File LTm == Local Time DMY == Day Month Year

1998 Edward Lee Campbell. All Rights Reserved

20

Java Identifier Naming Convention

21

Bibliography
The following bibliography lists books by subject that have influenced this convention. //*** update to include rapid development, java docs from sun,

Java
Flanagan, David, 1997. Java In A Nutshell, A Desktop Quick Reference, 2nd ed. Sebastpol, CA: OReilly & Associates, Inc.

Object Oriented Software Development


Booch, Grady, 1994. "Object-Oriented Analysis and Design with Applications", 2nd ed. Redwood City, CA: Benjamin/Cummings. Entsminger, Gary, 1995. "The Tao of Objects", 2nd ed. New York, NY: M&T Books Taylor, David A. 1990. "Object Oriented Technology: A Manager's Guide", Reading, MA: Addison-Wesley Publishing Company. White, Iseult and Goldberg, Marc 1994. "Using the Booch Method, A Rational Approach", Redwood City, CA: Benjamin/Cummings.

Software Development
McConnell, Steve 1993. "Code Complete, A Practical Handbook of Software Construction". Redmond WA: Microsoft Press. Maguire, Steve 1994. "Debugging the Development Process". Redmond WA: Microsoft Press. Maguire, Steve 1993. "Writing Solid Code". Redmond WA: Microsoft Press.

You might also like