Java OO Design & Coding Standards

a proposal by Ir. Marc Meurrens (A.Ir.Br.)

DRAFT - June 30, 1997

This page is a draft, submitted to the comments of my colleagues around the web and to the members of the Belgian Java User Group (BeJUG)
- Introduction and detailled table of contents
- The book Java Design : Building Better Apps and Applets by Peter Coad, Mark Mayfield
- Commented (and sometimes mirrorred) important links (more links are available here)
- Our own "Java OO Design & Coding Standards" proposal to be published in August 1997
- Informations on the current page (date, etc), forms to comment and/or add links, conventions in use, shortcuts.
Refer to this document as joodcs - DRAFT June 30, 1997 and, please, transmit its URL http://www.ulb.ac.be/esp/ip-Links/Java/joodcs to colleagues.
This document will be updated very often and will be entirely revised, with additional proposals, during this summer. If you want to receive notifications of upgrades, provide your e_mail.
Your comments are more than welcome: for your convenience, forms are provided at the bottom of this page. (This draft is written in "bad continental english" and will be translated to english before becoming a proposal. Be tolerant!)
The most important related papers are mirrored on our site for the convenience of belgian readers and to save the bandwidth. Mirror documents are said to be "revisited" as we added a few conventional informations (forms, etc); sometimes, we corrected minor HTML bugs; sometimes, we merged several sources. Official agreements of the original authors are pendent. Visit the original pages!

Introduction and detailled table of contents

During the june

meeting (June 21, 1997) of

BeJUG on Foundation Classes , a discussion occurred after the

excellent presentation of François Staes (

mailto:fstaes@innet.be) on

JDK 1.1 - AWT.

We pointed out the importance of using "interfaces". We agree on this point with most OO experts, e.g. Peter Coad. Let us quote here the (very explicit) opinion of Mark L. Fussell: "Interfaces are the primary mechanism that developers should be using to internally and externally couple their software: typing of variables, parameters, return values and casts should be primarily done using interfaces and not classes. Classes are implementations of interfaces and should provide no public behavior beyond the interface itself (other than how to create and initialize an object of that class)."
Note that, even if we mostly agree with this sentence, we'll show below that the last restriction "(other than how to create and initialize an object of that class)" is now obsolete, using factory classes (already suggested elsewhere by Mark Fussell) but also taking in account the new capabilities provided by "inner classes".
We seriously regret that the standard JDK does not systematically use "interfaces" and that the Microsoft's AFC (Application Foundations classes) ignore them completely!
We opened, but did not conclude, a debate on inheritance and composition. In the discussion, François shows the last book of Peter Coad and Mark Mayfield: "Java Design" (but I am not sure all the assistance noticed the exact references) where authors stress the use of composition over inheritance.
We discussed naming conventions for interfaces, classes, etc.

In this draft, we provide

A synthesis table of the authors and documents available or used within this site. Visit this page!
The exact reference of the (updated August 2, 1997) book of Coad and Mayfield
A few links
Our own proposal (based on JDK 1.1) will be published in August 1997.
If you want to receive notifications of upgrades, provide your e_mail. Comments, suggestions and additional ressources are more than welcome!

Java Design : Building Better Apps and Applets
by Peter Coad, Mark Mayfield

Java Design : Building Better Apps and Applets
(Yourdon Press Computing Series)
by

Peter Coad (

coad@oi.com) &

Mark Mayfield (

mlm@jencon.com)

Bk&Cd-r*NR Edition
Paperback, 350 pages
Published by Prentice Hall Computer Books
Publication date: January 1, 1997
Dimensions (in inches): 9.23 x 7.02 x .76
ISBN: 0132711494
$39.95

You'll find here miscellaneous data gathered from the official book homepage (provided by the publishers) at URL http://www.prenhall.com/allbooks/ptr_0132711494.html, from http://www.amazon.com where you may access reader's comments and order the book, and from the presentation published by Peter Coad him self (including large excerpts but without the images). This revisited mirror has been established with the kind agreement of Peter Coad.

A few links on Java standards, naming and coding conventions,etc
(in relation with OO design)

What you must read anyway...

You should also learn about other proposals...

Java conventions are generally a transposition of C/C++ conventions, as in...

What you should read if you have a C++ background...

Additional links related to C / C++ coding conventions...

C++

here

Indian Hill

Coding Standards Repository, etc

A few links on OO design

A few links on Program Documentation

Many other

Your

What you must read anyway...

Java Development Standards

is a revisited mirror (with kind agreement of Mark L. Fussell) of

http://www.chimu.com/publications/javaStandards/index.html by

Mark L. Fussell (

Mark.Fussell@ChiMu.com) This document describes the standards (

Coding and Design Standards) used by Mark L. Fussell for Java development. The reason to provide these standards is to help users of his frameworks to more easily understand and predict the interfaces of the subsystems. These standards may also be helpful to teams establishing or growing their own standards.
This is a ressource you must read!
(about 15 pages all mirrored on our site; with figures in the 2nd part (

design notations); the document includes

references to a clever selection of printed and online books)

(updated August 2, 1997) Java Design by Peter Coad (coad@oi.com) & Mark Mayfield (mlm@jencon.com)

is a revisited mirror site (established with the kind agreement of Peter Coad). An online beta version (without pictures) is available on Peter Coad's

book page and mirrored

here. File

coad-ppt.zip (172 kb --> 2,5 Mb , 43 slides) is a mirror of the PowerPoint presentation you may consider usefull. This new presentation, available on the site of Peter Coad (

http://www.oi.com), is a step forward into JDK 1.1 as it adds "event source/listener" and "property change source/support/listener."
Indeed, the current book's version was written with JDK 1.0.2. in mind.
To understand the additional OO capabilities of

JDK 1.1 stay tuned! ;-) or see the next ressource.

"Thinking in Java" (by Bruce Eckel)

is a revisited mirror (published with the agreement and the cooperation of the original author) of

http://www.EckelObjects.com/javabook.html where you can download this free book in Acrobat (

www.adobe.com) PDF format:

Thinking in Java Rev. 9, August 16, 1997 TJAVA9.PDF (2678 kb). Downloading the PDF file from the original site is quite difficult. The

TJAVA9.PDF Acrobat file, the

tjava9W95.zip file (1557 kb --> a 4349 kb WORD file), the CodePackager

tj9code.zip (122 kb --> 3 files, 1070 kb) and the

CodePackager java source are mirrored on our site. A detailled description of all

chapters and an important

errata note are also available. This book has been written by Bruce Eckel (

Bruce@EckelObjects.com), also author of

"Thinking in C++".

You should also learn about other proposals...

Remember there is no ONE accepted standard!

(updated August 2, 1997) Draft Java Coding Standard: is a revisited mirror (published with the kind agreement of the author, Doug Lea) of http://gee.cs.oswego.edu/dl/html/javaCodingStd.html by Doug Lea (dl@cs.oswego.edu). This document includes a section Structure and Documentation (Standard ways to write and document constructions) and a section Naming conventions (Standard ways to name identifiers: class names, method names, variable names, etc).
It also includes a large number of usefull recommendations (with rationale!): some rules of thumb that tend to avoid common errors and development obstacles. You can use these guidelines to make your own design and coding checklists to be used in retrospective code clean-up or when classes need to be used in new contexts or placed in reusable libraries.
Also a few links to other style guidelines etc. The form of these guidelines is based on example coding standards and checklists in Watts Humphrey's book A Discipline for Software Engineering, Addison-Wesley, 1995, along with author's experience.
(added August 2, 1997) AmbySoft Inc. Java Coding Standards: is a revisited mirror (with the agreement of the original author Scott W. Ambler) of http://WWW.AmbySoft.com/javaCodingStandards.html by Scott W. Ambler (ambler@hookup.net)
Includes 2 PDF files where the author seriously documents his proposal. You'll find here a structured sum of ideas and proposals gathered from miscellaneous authors.
The Navy Java Style Guide: is essentially intented for the students of the N.P.S. School (some recommandations are not exportable outside the school). It is available on our site as a revisited mirror (original author's agreement pending) of http://vislab-www.nps.navy.mil/~java/course/styleguide.html (Last Updated 8 JUL96) by the Naval Postgraduate School (java@nps.navy.mil(JAVAPage)). The Java style guide is mirrored from the NPS CS C++ style guide used and developed by John Falby.
Unfortunately, some features available only in C++ (enum, typedef, cout, etc) were NOT removed! So, handle this text with care!!!
The Java Coding Style Guidelines: are available on our site as a revisited mirror (original author's agreement pending) of http://reality.sgi.com/sandvik/JavaGuidelines.html (February 2, 1996. Revision: 1.2) by Kent Sandvik (sandvik@sgi.com)
A subset of Stephan Janssen's "FICS Java Coding Standards": (9 may 1997, rev. 1.33) is available here by courtesy of Stephan; these notes include recommandations used within FICS together with a compilation of usefull rules gathered from various sources; we decided to remove the internal FICS recommandations from the (not publicly available) original document. For more details, contact sja@bejug.org
Advanced Java: Idioms, Pitfalls, Styles, and Programming Tips: is a revisited mirror (published with the kind encouragements of the original author) of http://members.aol.com/laffra/book.html by Chris Laffra (laffra@aol.com)
(added August 4, 1997) Coding Style and Good Computing Practices: is a revisited mirror (original author's agreement pending) of http://wizard.ucr.edu/~nagler/coding_style.html by Jonathan Nagler (nagler@wizard.ucr.edu)
This article appeared in The Political Methodologist Spring, 1995 - Volume 6, No 2.
While not directly related to Java or any other language or OO design, this paper provides important concepts to be applied in OO design and Java programming.

Java conventions are generally a transposition of C/C++ conventions, as in...

The NASA Coding Standards for C, C++, and Java

by Vision 2000 CCS Package and Application Team are available on our site as a revisited mirror under construction (!) of

http://v2ma09.gsfc.nasa.gov/coding_standards.html
The purpose of these coding standards is to facilitate the maintenance, portability, and reuse of custom C, C++, and Java source code developed for the Vision 2000 CCS. These standards were developed from a variety of sources, including other standards documents, software examples from defacto standard language references, and personal experience.
This document is organized into four sections:

File Organization - source file contents and layout
Naming Conventions - how to name files and identifiers
Style Guide - guidelines for how source code should look
Recommended Programming Practices

But here is what you should read if you have a C++ background...

The Taligent's Java Cookbook for porting C++ to Java,: published here with the kind agreement of the author: Mark Davis (cookbook@taligent.com), includes step-by-step recommendations by the C++ IBM's subsidiary. But, it also includes important discussions on design and coding features you may not miss. However, the paper will probably be difficult for readers without C++ background. We mirror on our site the original http://www.taligent.com/Technology/WhitePapers/PortingPaper/index.html paper dated March 25, 1997. An Acrobat (www.adobe.com) PDF file is available here; you may download the mirror file Java_Cookbook.pdf from our site; visit also the Java Cookbook News Group

Additional links related to C / C++ coding conventions...

We propose here a few links related to C++
More links are available here.

Todd Hoff's C++ Coding Standards: are available on our site as a revisited mirror under construction (!) of http://www.possibility.com/Cpp/CppCodingStandard.html (an obsolete mirror -version of FEB 12, 1997- is also available at URL http://www.cs.umd.edu/users/cml/cstyle/CppCodingStandard.html) The version dated June 3, 1997 (mirrored on our site) includes a large number of links you should consider (a.o. http://www.possibility.com/Cpp/DesignStories.html Design Stories by Todd Hoff); Visit also the main page http://www.possibility.com/Cpp/ of Todd Hoff mailto:tmh@possibility.com
Programming in C++, Rules and Recommendations (161 kb) from Ellemtel (Swedish Telecom): is available on our site as a revisited mirror (original author's agreement pending) of http://www.cs.umd.edu/users/cml/cstyle/Ellemtel-rules.html by Mats Henricson (mats.henricson@eua.ericsson.se). and Erik Nyquist (erik.nyquist@eua.ericsson.se); 68 pages; Acrobat (www.adobe.com) PDF and Postscript versions are available; documents collected by mailto:cml@cs.umd.edu; an alternative mirror http://www.doc.ic.ac.uk/lab/cplus/c++.rules/ seems obsolete.
C++ Programming Style with Rationale: by Keith Gabryelski mailto:ag@wildfire.com; the C++ style guide from Wildfire Communications is available on our site as a revisited mirror under construction (!) of URL http://www.wildfire.com/~ag/Engineering/Development/C++Style/
Another mirror (by mailto:cml@cs.umd.edu) exists at URL http://www.cs.umd.edu/users/cml/cstyle/Wildfire-C++Style.html;

If you know other links on the same topics

or if you want to comment on the links already suggested, please use the form provided below.

Our proposal

The draft submitted to your comments will be published in August 1997.
If you want to receive notifications of upgrades, provide your e_mail. Comments, suggestions and additional ressources are more than welcome!