Coding standards for Java

[mish]

I have been commissioned to write articles on coding standards for a
well known publishing firm. I have written these articles and now
need to test them out on a sample population of the sort of people we
expect to finally read them!

Would anyone here mind reviewing them for me? I am particularly
interested in the Java Coding Standards article being reviewed fairly
thoroughly!

The files are at the following urls:
General coding standards articles
http://mishj.brinkster.net/intranet/codingstds.doc
http://mishj.brinkster.net/intranet/codingstds2.doc

Java coding standards
http://mishj.brinkster.net/intranet/javacodingstds.doc

Please send any feedback to (e-mail address removed)
or post the feedback in here.

Thanks In Advance!
Michelle Johnston

 

[Wendy S]

Would anyone here mind reviewing them for me? I am particularly
interested in the Java Coding Standards article being reviewed fairly
thoroughly!

I wouldn't mind, but not in MS Word format... try PDF, HTML or plain text.

 

[Doug]

Here's a quick review:

You bemoan the fact that hand-written HTML can produce open tags without the
corresponding closing tag. However, I don't see any mention of using a
validator to enforce an HTML standard. I would encourage any non-trivial
HTML project to require validation through something like
http://validator.w3.org/ before the page is posted.

I gotta complain about how you format your tables. The alternating shading,
combined with the plethora of fonts, makes for what I euphemistically call
a "ransom note" effect. I would settle on one or two styles of tables, and
forget numbering table rows, it add nothing to the information you are
trying to convey.

You need a "Document Conventions" section that explains what constant font
indicates (a Java keyword?), etc.

I would also delete the last paragraph of "javacodingstds.doc", remove the
shading for the sample company standards doc (the last 12 pages), and just
introduce the section by changing "Below I have drafted some sample coding
standards for a fictional company called The Open Company" to "The rest of
this document is a draft of some sample coding standards for a fictional
company called The Open Company".


doug

 

[Jacob]

Java coding standards
http://mishj.brinkster.net/intranet/javacodingstds.doc

Same comment on .doc as already mentioned; Not everyone
has OpenOffice installed rememeber... ;-)

General comment is that this is not Java coding standard
but a mixture of lots of things:

o Programming source code in general
o Java programming source code in particular
o Java programming best practices
o Development environment (OS, VCS, IDE,
BugTracking, build, etc.)
o System architechture (DB, packaging, AppServer,
i18n, etc.)
o GUI Design (design, help, configuration etc.)
o Process documentation (code review practice etc.)
o Delivery / deployment (security etc.)

A typical development organization will have separate
specifications for each of these parts. So either you'll
have to clean up this mess, or change the scope to cover
it all. And in that case *lots* are missing!!

A few specific comments:

* The guide is unusable during reviews as you cannot
refer to specific sections.
* The section about file extension is superflous as it
is mandatory anyway (.java / .class). However source
contains much more than these; What about images,
properties, translation files, .txt, configs etc?
* Same with Javadoc comments: "... must start with /**...".
It's not one if it doesn't.
* Don't include rules for how *NOT* to do things; There
are really to much to cover ("Method names do NOT have
a prefix...", "do NOT use Hungarian notation..." etc.)
* What about boolean functions prefixed by "is"?
* There is a lack of rationale behind most of the
statements (Why should indentation be 4?, Why should
the opening brace be where it is? Why should the
opening "/" of a file be in column 4? Etc.)
* "pascal case" and "camel case" needs a definition.
These are silly terms really.
* Your "breaking line" examples are completely out of
order.
* About braces: "the closing brace should be the only
character on the line...". The statement doesn't match
your example "} catch (Exception e) {".
* The mapping between Java and .Net packages seems
completely out of place.

Missing:

* Naming in general (abbreviations, iterators etc.)
* Special naming conventions (is/set/get etc.)
* Use of whitespace.
* ...

Check http://geosoft.no/javastyle.html for hints on
scope, form and content for a guidelines like these.

 

[mish]

I would just like to say thanks to all who made comments here, they
are duly noted. Sorry these docs arent available in html at this time
as the publishing house takes my articles in word format and produce
the html from them at that point - they will be in html when published
dont worry!

I knew there would be lots of issues, glad to get them now before
publication!

Watch out for the finished articles at www.informit.com in about two
weeks time!

Thanks again
Michelle