Writing Robust Java Code - AmbySoft

javaCodingStandards.pdf

Writing Robust Java Code

The AmbySoft Inc. Coding Standards for Java v17.01d

Scott W. Ambler Software Process Mentor

This Version: January 15, 2000

Copyright 1998-1999 AmbySoft Inc.

javaCodingStandards.pdf

This page left unintentionally blank. (yuk yuk yuk)

Copyright 1998-1999 AmbySoft Inc.

javaCodingStandards.pdf

Purpose of this White Paper

This white paper describes a collection of standards, conventions, and guidelines for writing solid Java code. They are based on sound, proven software engineering principles that lead to code that is easy to understand, to maintain, and to enhance. Furthermore, by following these coding standards your productivity as a Java developer should increase remarkably ? Experience shows that by taking the time to write high-quality code right from the start you will have a much easier time modifying it during the development process. Finally, following a common set of coding standards leads to greater consistency, making teams of developers significantly more productive.

Important Features of This White Paper

? Existing standards from the industry are used wherever possible ? You can reuse more than just code. ? The reasoning behind each standard is explained so that you understand why you should follow it. ? Viable alternatives, where available, are also presented along with their advantages and disadvantages

so that you understand the tradeoffs that have been made. ? The standards presented in this white paper are based on real-world experience from numerous object-

oriented development projects. This stuff works in practice, not just theory. ? These standards are based on proven software-engineering principles that lead to improved

development productivity, greater maintainability, and greater enhancability.

Target Audience

Professional software developers who are interested in: ? Writing Java code that is easy to maintain and to enhance ? Increasing their productivity ? Working as productive members of a Java development team

Help Me Improve These Standards

Because I welcome your input and feedback, please feel free to email me at scott@ with your comments and suggestions. Let's work together and learn from one another.

Acknowledgments

The following people have provided valuable input into the development and improvement of these standards, and I would like to recognize them for it.

Stephan Marceau Eva Greff Graham Wright Larry Allen John Pinto Bill Siggelkow Kathy Eckman Kyle Larson Mark Brouwer

Lyle Thompson Wayne Conrad Alex Santos Dick Salisbury Vijay Eluri Camille Bell Guy Sharf Robert Marshall Gerard Broeksteeg

David Pinn Michael Appelmans Kiran Addepalli Bruce Conrad Carl Zimmerman Fredrik Nystrom Scott Harper Peter C.M. Haight Helen Gilmore

Larry Virden William Gilbert Brian Smith Michael Finney Hakan Soderstrom Cory Radcliff

Scott W. Ambler January 2000

Copyright 1998-1999 AmbySoft Inc.

javaCodingStandards.pdf

This page also left unintentionally blank. (although now it isn't quite as funny)

Copyright 1998-1999 AmbySoft Inc.

javaCodingStandards.pdf

i

Table of Contents

1. GENERAL CONCEPTS.........................................................................................................................................1

1.1 WHY CODING STANDARDS ARE IMPORTANT ........................................................................................... 1 1.2 THE PRIME DIRECTIVE.................................................................................................................................. 1 1.3 WHAT MAKES UP A GOOD NAME .............................................................................................................. 2 1.4 GOOD DOCUMENTATION.............................................................................................................................. 3

1.4.1 The Three Types of Java Comments .......................................................................................................4 1.4.2 A Quick Overview of javadoc..................................................................................................................5 1.5 AMBLER'S LAW OF STANDARDS................................................................................................................. 6

2. STANDARDS FOR MEMBER FUNCTIONS ....................................................................................................7

2.1 NAMING MEMBER FUNCTIONS.................................................................................................................... 7 2.1.1 Naming Accessor Member Functions....................................................................................................7 2.1.1.1 Getters ................................................................................................................................................. 7 2.1.1.1.1 Alternative Naming Convention for Getters ? Has and Can.................................................. 8 2.1.1.2 Setters ................................................................................................................................................. 8 2.1.1.3 Constructors ...................................................................................................................................... 8

2.2 MEMBER FUNCTION VISIBILITY ................................................................................................................. 9 2.3 DOCUMENTING MEMBER FUNCTIONS....................................................................................................... 9

2.3.1 The Member Function Header................................................................................................................9 2.3.2 Internal Documentation.........................................................................................................................11 2.4 TECHNIQUES FOR WRITING CLEAN CODE............................................................................................... 12 2.4.1 Document Your Code..............................................................................................................................12 2.4.2 Paragraph/Indent Your Code ...............................................................................................................13 2.4.3 Paragraph and Punctuate Multi-Line Statements............................................................................13 2.4.4 Use Whitespace in Your Code...............................................................................................................14 2.4.5 Follow The Thirty-Second Rule............................................................................................................14 2.4.6 Write Short, Single Command Lines....................................................................................................14 2.4.7 Specify the Order of Operations...........................................................................................................14 2.5 JAVA CODING TIPS....................................................................................................................................... 15 2.5.1 Organize Your Code Sensibly...............................................................................................................15 2.5.2 Place Constants on the Left Side of Comparisons............................................................................15

3. STANDARDS FOR FIELDS (ATTRIBUTES/PROPERTIES)......................................................................16

3.1 NAMING FIELDS............................................................................................................................................ 16 3.1.1 Use a Full English Descriptor for Field Names.................................................................................16 3.1.1.1 Alternative ? Hungarian Notation ................................................................................................ 16 3.1.1.2 Alternative ? Leading or Trailing Underscores .......................................................................... 17 3.1.2 Naming Components (Widgets)............................................................................................................17 3.1.2.1 Alternative for Naming Components ? Hungarian Notation .................................................... 17 3.1.2.2 Alternative for Naming Components ? Postfix-Hungarian Notation....................................... 17 3.1.3 Naming Constants...................................................................................................................................18 3.1.4 Naming Collections................................................................................................................................19 3.1.4.1 Alternative for Naming Collections ? The `Some' Approach................................................... 19 3.1.5 Do Not "Hide" Names............................................................................................................................19

3.2 FIELD VISIBILITY......................................................................................................................................... 20 3.3 DOCUMENTING A FIELD ............................................................................................................................. 21 3.4 THE USE OF ACCESSOR MEMBER FUNCTIONS........................................................................................ 21

3.4.1 Naming Accessors ...................................................................................................................................22 3.4.2 Advanced Techniques for Accessors....................................................................................................23

3.4.2.1 Lazy Initialization............................................................................................................................. 23

Copyright 1998-2000 AmbySoft Inc.

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download