Coding standards for Java

Discussion in 'Java' started by mish, Jun 27, 2003.

  1. mish

    mish Guest

    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
    or post the feedback in here.

    Thanks In Advance!
    Michelle Johnston
    mish, Jun 27, 2003
    #1
    1. Advertising

  2. mish

    Wendy S Guest

    "mish" <> wrote in message
    news:...
    > 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.

    --
    Wendy in Chandler, AZ
    Wendy S, Jun 27, 2003
    #2
    1. Advertising

  3. mish

    Doug Guest

    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

    "mish" <> wrote in message
    news:...
    > 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
    > or post the feedback in here.
    >
    > Thanks In Advance!
    > Michelle Johnston
    Doug, Jun 28, 2003
    #3
  4. mish

    Jacob Guest

    mish wrote:
    > 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.
    Jacob, Jun 30, 2003
    #4
  5. mish

    mish Guest

    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
    mish, Jul 1, 2003
    #5
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Jim Culver

    coding standards

    Jim Culver, Sep 9, 2003, in forum: ASP .Net
    Replies:
    4
    Views:
    2,211
  2. shbgupta

    coding standards

    shbgupta, Jun 27, 2003, in forum: ASP .Net
    Replies:
    2
    Views:
    542
    Chance Hopkins
    Jun 27, 2003
  3. =?Utf-8?B?UHJhdmVlbg==?=

    ASP.NET Coding Standards

    =?Utf-8?B?UHJhdmVlbg==?=, Aug 12, 2004, in forum: ASP .Net
    Replies:
    4
    Views:
    8,434
    Kevin Spencer
    Aug 12, 2004
  4. Adam Knight

    C# coding Standards!!!

    Adam Knight, Jan 11, 2006, in forum: ASP .Net
    Replies:
    3
    Views:
    822
    Karl Seguin [MVP]
    Jan 11, 2006
  5. mish

    Coding standards

    mish, Sep 24, 2003, in forum: Java
    Replies:
    1
    Views:
    426
    RJGraham
    Sep 25, 2003
Loading...

Share This Page