DOC

Java Style Guide

By Kristen Pierce,2014-04-24 11:42
7 views 0
Java Style Guide

    NASA GSFC Data Systems Technology Java Style Guide, Version 1.0 DSTL-97-

    002

    NASA GSFC

    Data Systems Technology

    Java? Style Guide

    July 1997

    Sylvia B. Sheppard Date Head, Software and Automations Systems Branch Code 522

    Julia D. Breed Date Head, Applied Technology Development Section Code 522.1

    Goddard Space Flight Center

    Greenbelt, Maryland

NASA GSFC Data Systems Technology Java Style Guide, Version 1.0 DSTL-97-

    002

    PREFACE

    This document describes recommended practices and styles for programmers using the Java

    language in the Software and Automation Systems Branch, Code 522. Guidelines are based on

    generally recommended software engineering techniques, industry resources, and local convention.

    This document is under the configuration management of the Software and Automation Systems

    Branch Configuration Control Board (CCB). Changes to this document shall be made by

    Documentation Change Notice (DCN), reflected in text by change bars, or by complete revision.

    Requests for copies of this document, along with questions and proposed changes, should be

    addressed to:

    Technology Support Office

    Advanced Architectures and Automation Branch, Code 588

    Goddard Space Flight Center

    Greenbelt, Maryland 20771

Or see our Web site at:

    http://aaaprod.gsfc.nasa.gov/WebSite/

    Java and other Java-based names are trademarks of Sun Microsystems, Inc.

    This document assumes that the reader is familiar with the Java language and understands basic

    object-oriented concepts.

    While every precaution has been taken in the preparation of this document, the authors assume no

    responsibility for errors or omissions.

    iii/iv

    NASA GSFC Data Systems Technology Java Style Guide, Version 1.0 DSTL-97-

    002

    CHANGE INFORMATION PAGE

    List of Effective Pages

    Page Number Issue

    Title Original

    Signature Page Original

    iii through x Original

    1-1 and 1-2 Original

    2-1 and 2-11 Original

    3-1 through 3-9 Original

    4-1 through 4-3 Original

    5-1 Original

    I-2 and I-2 Original

    Document History

    Issue Date DCN No. Original July 1997 N/A

    v/vi

NASA GSFC Data Systems Technology Java Style Guide, Version 1.0 DSTL-97-

    002

    ACKNOWLEDGMENTS

    The following developers of the guidelines gave generously of their time and expertise during the

    process of development:

    Troy Ames

    Julia Breed

    Carl Hostetter

    Stephen Jonke

    Jeremy Jones

    Lisa Kane

    Karl Mueller

    Gregory Shirah

    Mark Stirling

    Robert Wiegand

    vii/viii

NASA GSFC Data Systems Technology Java Style Guide, Version 1.0 DSTL-97-

    002

    TABLE OF CONTENTS

Section 1: Introduction

    1.1 Purpose ...................................................................................................................................... 1-1 1.2 Audience .................................................................................................................................... 1-1 1.3 Document Format ..................................................................................................................... 1-1 1.4 Relevant Documents ................................................................................................................. 1-2

Section 2: Consistent Formatting

    2.1 White Space ............................................................................................................................... 2-1

    2.1.1 Blank Lines ............................................................................................................ 2-1

    2.1.2 Spacing ................................................................................................................... 2-2

    2.1.3 Indentation ............................................................................................................. 2-3

    2.1.4 Continuation Lines ................................................................................................. 2-3

    2.1.5 Braces and Parentheses ......................................................................................... 2-4

    2.2 Comments .................................................................................................................................. 2-6

    2.2.1 Documentation Comments ..................................................................................... 2-6

    2.2.2 Code Comments ...................................................................................................... 2-7

     2.2.2.1 Code Comment Formats ........................................................................... 2-7

     2.2.2.2 General Guidelines ................................................................................... 2-8

    2.3 Standard Naming Conventions ................................................................................................. 2-9

    2.3.1 Name Formats ........................................................................................................ 2-9

    2.3.2 Name Conventions ................................................................................................. 2-9

    2.3.3 Short Names ......................................................................................................... 2-10

    2.3.4 General Guidelines for Variable Names .............................................................. 2-10

    2.3.5 Package Naming Conventions ............................................................................. 2-10

    2.4 Literals .................................................................................................................................... 2-11

Section 3: File Organization

    3.1 Packages .................................................................................................................................... 3-1 3.2 README File............................................................................................................................ 3-1 3.3 File Prolog ................................................................................................................................. 3-1 3.4 Order of Contents ...................................................................................................................... 3-2 3.5 Classes and Interfaces............................................................................................................... 3-2 3.6 Methods ..................................................................................................................................... 3-3 3.7 Tagged Paragraphs ................................................................................................................... 3-4 3.8 Sample Source File .................................................................................................................... 3-5

Section 4: Use of Language Constructs

    4.1 Import ........................................................................................................................................ 4-1 4.2 Methods ..................................................................................................................................... 4-1 4.3 Variables.................................................................................................................................... 4-1 4.4 Literals ...................................................................................................................................... 4-1 4.5 Type Conversions and Casts ..................................................................................................... 4-4 4.6 Operators and Expressions ....................................................................................................... 4-2 4.7 Control Flow Statements .......................................................................................................... 4-3 4.8 Threads...................................................................................................................................... 4-3

Section 5: Tips and Techniques

    5.1 Classes ....................................................................................................................................... 5-1 5.2 Threads...................................................................................................................................... 5-1 5.3 Portability.................................................................................................................................. 5-1 5.4 Performance .............................................................................................................................. 5-2

    ix

NASA GSFC Data Systems Technology Java Style Guide, Version 1.0 DSTL-97-

002

ix

NASA GSFC Data Systems Technology Java Style Guide, Version 1.0 DSTL-97-

    002

    EXAMPLE CODE

    2.1.1a Code Paragraphing ............................................................................................................. 2-1 2.1.4a Strings of Conditional Operators ........................................................................................ 2-3 2.1.4b Method Call ......................................................................................................................... 2-3 2.1.5a Braces-Stand-Along Method ............................................................................................... 2-4 2.1.5b Braces Improve Readability ................................................................................................ 2-4 2.1.5c No Braces - Difficult to Read .............................................................................................. 2-4 2.1.5d Use of Braces ....................................................................................................................... 2-5 2.1.5e Dummy Body ...................................................................................................................... 2-5 2.2a Document Comment ........................................................................................................... 2-6 2.2b Boxed Comment .................................................................................................................. 2-7 2.2c Section Separator ................................................................................................................ 2-7 2.2d Block Comment ................................................................................................................... 2-7 2.2e In-line Comments................................................................................................................ 2-7 2.2f Block Comments vs. In-line Comment ............................................................................... 2-8

    2.2g Comment Indentation ......................................................................................................... 2-8 4.7a Embedded Assignment Alternatives .................................................................................. 4-2

    4.8a Complex Conditional Expression ...................................................................................... 4-3

    x

Software and Automation Systems Branch Java Style Guide, Version 1.0 DSTL-

    97-002

    SECTION 1

    INTRODUCTION 1.1 PURPOSE

    This document describes the style recommended by the Data Systems Technology Division for

    writing Java programs, where the goals are to produce code that is:

     Reliable

     Maintainable

    - Organized

    - Easy to understand

    - Well documented

    1.2 AUDIENCE

    This document was written specifically for programmers in the Data Systems Technology Division

    environment. This document assumes a working knowledge of Java, and focuses on describing good

    practices that will enhance the quality of the Java code.

    1.3 DOCUMENT FORMAT The following meanings are assigned to the formats included in this document:

Example code is included in shaded boxes.

Plain boxes are used to enclose standard formats and other related information.

Italics are used to differentiate the variable portion to be completed by the programmer from the

    standard format that should appear verbatim.

Italics are also used to visually separate brief (one-line) examples.

Bold text is used simply to highlight key words or phrases for the reader.

    1-1

Software and Automation Systems Branch Java Style Guide, Version 1.0 DSTL-

    97-002

    1.4 RELEVANT DOCUMENTS

[1] The Software and Automation Systems Branch C++ Style Guide, Version 2.0, DSTL-96-011

     http://groucho.gsfc.nasa.gov/Code_520/Code_522/Documents/Cplus/

    [2] The Java Programming Language, Arnold and Gosling

     Addison-Wesley, 1996

    [3] The Java Language Specification, Version 1.0

     http://www.javasoft.com:81/docs/language_specification/

    [4] The JavaBeans 1.0 API Specification

     http://splash.javasoft.com/beans/spec.html

[5] Draft Java Coding Standard, Lea

     http://g.oswego.edu/dl/html/javaCodingStd.html

[6] Java Optimization

     http://www.cs.cmu.edu/~jch/java/optimization.html

    1-2

Software and Automation Systems Branch Java Style Guide, Version 1.0 DSTL-

    97-002

    SECTION 2

    CONSISTENT FORMATTING

The guidelines in this section are written to improve the consistency of formatting of Java

    programming style within the Branch. This will ease the job of maintenance, and will also make it

    easier for a programmer to transfer from one project to another.

    2.1 WHITE SPACE Adding white space in the form of blank lines, spaces, and indentation significantly improves the readability of code.

    2.1.1 BLANK LINES

    There should be at least one blank line between methods. Within a method careful use of blank

    lines between code "paragraphs" can greatly enhance readability by making the logical structure of

    a sequence of lines more obvious. Using blank lines to create paragraphs in code or comments can

    make programs more understandable. The following example illustrates how the use of blank lines

    helps break up lines of text into meaningful portions.

    Example 2.1.1a - Code Paragraphing

     public void joinGroupSucceeded(JoinGroupSuccessEvent e) { Group g = getPendingGroup(e.getGroupName()); if (g != null) { // Remove g from the pending list fPendingGroupTable.remove(g.getName()); // Add the group to the joined group list fJoinedGroupTable.put(g.getName(), g); } // Notify listeners of the event: Vector listeners = null; synchronized(this) { listeners = (Vector) fJoinGroupSuccessListeners.clone(); } for (int i = 0; i < listeners.size(); ++i) { ((JoinGroupSuccessListener) listeners.elementAt(i)).joinGroupSucceeded(e); } }

    However, overuse of blank lines can defeat the purpose of grouping and can actually reduce

    readability. Therefore, a single blank line should be used to separate sections of code within a

    method.

    2-1

Report this document

For any questions or suggestions please email
cust-service@docsford.com