Java Programming Standards & Reference Guide Version 3.2 Office of Information & Technology Department of Veterans Affairs Java Programming Standards & Reference Guide, Version 3.2 REVISION HISTORY DATE VER. DESCRIPTION AUTHOR CONTRIBUTORS 10-26-15 3.2 Added Logging Sid Everhart JSC Standards , updated Vic Pezzolla checkstyle installation instructions and package name rules. 11-14-14 3.1 Added ground rules for Vic Pezzolla JSC enforcement 9-26-14 3.0 Document is continually Raymond JSC and several being edited for Steele OI&T noteworthy technical accuracy and / PD Subject Matter compliance to JSC Experts (SMEs) standards. 12-1-09 2.0 Document Updated Michael Huneycutt Sr 4-7-05 1.2 Document Updated Sachin Mai L Vo Sharma Lyn D Teague Rajesh Somannair Katherine Stark Niharika Goyal Ron Ruzbacki 3-4-05 1.0 Document Created Sachin Sharma i Java Programming Standards & Reference Guide, Version 3.2 ABSTRACT The VA Java Development Community has been establishing standards, capturing industry best practices, and applying the insight of experienced (and seasoned) VA developers to develop this “Java Programming Standards & Reference Guide”. The Java Standards Committee (JSC) team is encouraging the use of CheckStyle (in the Eclipse IDE environment) to quickly scan Java code, to locate Java programming standard errors, find inconsistencies, and generally help build program conformance. The benefits of writing quality Java code infused with consistent coding and documentation standards is critical to the efforts of the Department of Veterans Affairs (VA). This document stands for the quality, readability, consistency and maintainability of code development and it applies to all VA Java programmers (including contractors). Adherence to these standards and rules will become a measurement of the quality of their work. NOTE: Good Java programming practices empower new personnel to quickly grasp the intention and purpose of the application, understand the style and theme being used, and construct enhancements that blend in well. Please read and follow the standards, conventions, suggestions, and general concerns outlined in this document. This document will continue to evolve and is meant to be a helpful programmer’s tool. • All aspects of mature software development are implemented when new code can be written and Quality-Inspected quickly and thoroughly. • Most software is not maintained indefinitely by the original software developer. It is maintained by a multitude of contributing software engineers that in time will add patches, tighten the code, add functionality, and keep the applications current to the latest standards. • Feedback in the form of corrections or suggestions for improvement of this document is encouraged in order to remove useless parts and add new parts as the Java language itself evolves. • The VA JSC is comprised of volunteers that champion these standards to attain the industry proven benefits for VA. • The developed software must comply with the appropriate standards and conventions established for the programming language found in the Technical Reference Model/Standards Profile (TRMSP). • The VA requires a 508 compliance certificate along with other documentation to certify software compliance prior to acceptance. ii Java Programming Standards & Reference Guide, Version 3.2 • Comments may be sent to the VA OI&T Java Standards Committee <[email protected]> "Any fool can write code that a computer can understand. Good programmers write code that humans can understand." By Mr. Martin Fowler, On Refactoring: Improving the Design of Existing Code iii Unknown Field Code Changed ... [1] Unknown Java Programming Standards & Reference Guide, Version 3.2 Field Code Changed ... [2] Unknown TABLE OF CONTENTS Field Code Changed ... [3] Unknown 1 OVERVIEW ....................................................................................................... 1 Field Code Changed ... [4] Unknown 1.1 Introduction .............................................................................................. 1 Field Code Changed ... [5] 1.2 Standards and Conventions Derivation ................................................... 2 Unknown Field Code Changed ... [6] 1.3 The Benefits of Using a Consistent Style ................................................ 3 Unknown 1.4 Intended Audience .................................................................................. 3 Field Code Changed ... [7] Unknown 1.5 Terminologies Used in This Guide .......................................................... 4 Field Code Changed ... [8] 1.6 Technology .............................................................................................. 6 Unknown Field Code Changed ... [9] 1.7 Enforcement ............................................................................................ 6 Unknown 1.8 Acknowledgements ................................................................................. 7 Field Code Changed ... [10] Unknown 1.9 Source File Organization ......................................................................... 8 Field Code Changed ... [11] 1.10 Source File Naming.............................................................................. 8 Unknown Field Code Changed ... [12] 1.11 Package Declaration ............................................................................ 8 Unknown 2 NAMING CONVENTIONS ................................................................................. 9 Field Code Changed ... [13] Unknown 2.1 Package Names ...................................................................................... 9 Field Code Changed ... [14] 2.2 Type Names ............................................................................................ 9 Unknown Field Code Changed ... [15] 2.3 Member Names ....................................................................................... 10 Unknown 2.4 Method Names ........................................................................................ 11 Field Code Changed ... [16] Unknown 2.5 Constant Names ...................................................................................... 12 Field Code Changed ... [17] 2.6 Parameter Names ................................................................................... 13 Unknown Field Code Changed ... [18] 2.7 Static Variable Names ............................................................................. 13 Unknown 2.8 Specific Naming Conventions ................................................................. 14 Field Code Changed ... [19] Unknown 3 DOCUMENTATION ........................................................................................... 16 Field Code Changed ... [20] 3.1 Beginning Comments .............................................................................. 17 Unknown Field Code Changed ... [21] 3.2 General Comment Formats ..................................................................... 17 Unknown 3.2.1 Block Comments ........................................................................... 17 Field Code Changed ... [22] Unknown 3.2.2 Single-Line Comments .................................................................. 18 Field Code Changed ... [23] 3.2.3 Trailing Comments ........................................................................ 19 Unknown Field Code Changed ... [24] 3.2.4 End-Of-Line Comments ................................................................. 19 Unknown 3.3 Comments with TODO or FIXME ............................................................ 20 Field Code Changed ... [25] Department of Vete…, 3/29/2016 8:26 AM 3.4 Javadoc Comments ................................................................................. 20 Deleted: 19 3.5 Type Javadoc .......................................................................................... 22 Unknown Field Code Changed ... [26] 3.6 Method Javadoc ...................................................................................... 22 Department of Vete…, 3/29/2016 8:26 AM Deleted: 20 iv Unknown Field Code Changed ... [27] Department of Vete…, 3/29/2016 8:26 AM Deleted: 20 Department of Vete…, 3/29/2016 8:26 AM Deleted: 21 Unknown Field Code Changed ... [28] Unknown Field Code Changed ... [29] Department of Vete…, 3/29/2016 8:26 AM Unknown Field Code Changed ... [30] Department of Vete…, 3/29/2016 8:26 AM Unknown Field Code Changed ... [31] Department of Vete…, 3/29/2016 8:26 AM Unknown Field Code Changed ... [32] Department of Vete…, 3/29/2016 8:26 AM Java Programming Standards & Reference Guide, Version 3.2 Deleted: 25 Department of Vete…, 3/29/2016 8:26 AM Deleted: 25 3.7 Variable Javadoc ..................................................................................... 24 Unknown 3.8 Style Javadoc .......................................................................................... 24 Field Code Changed ... [33] Unknown 4 STYLE ............................................................................................................... 26 Field Code Changed ... [34] 4.1 Coding Size Limits ................................................................................... 26 Department of Vete…, 3/29/2016 8:26 AM Deleted: 27 4.2 Maximum Line Length ............................................................................. 26 Department of Vete…, 3/29/2016 8:26 AM 4.3 Maximum File Length .............................................................................. 26 Deleted: 27 Unknown 4.4 Maximum Anonymous Inner Class Length .............................................