Writing Java Guidelines by Using Citations from Established References

Here are some slides with examples for Java programming standards or guidelines where the approach is to cite established works (Effective Java, Java Elements of Style, Code Conventions for the Java Programming Language, etc.) and to avoid as much as possible writing the standards or guidelines "from scratch".  This covers samples as you would see them in the document that cover several situations which occur when taking this approach.
The simple citation.  This is the easiest.  You come up with a summary title for the guidance you want followed, summarize the guidance (~1 paragraph), and cite in a reference where people can look up more information.  Experienced developers will already understand the topic and to them you are providing a decision about what to do.  Novices may not understand the topic and for them you have provided a resource where they should be able to get the topic explained, see code examples, etc.  This has the nice benefit of avoiding a "re-inventing the wheel" situation where in your guidance you replicate instructions, code samples, etc. that are already available in public materials.
Note that the titles often have numbers or some other unique identifier in them so that they can be more easily cited in test cases, referenced in contracts, etc.
Guidance without citation. Not every topic in a project or enterprise guideline can draw from established references.  There will necessarily be material about naming conventions, use of enterprise services, logon or security procedures, etc. that are specific to the enterprise and need explanation.  In this case, the guidance follows a more traditional route of including more detailed information and will usually include code examples.
Multiple citations.  Some of the more universal topics are going to appear in many references - e.g. how best to initialize strings, how to prevent security problems with array overflows, etc.  In these cases it can be valuable to cover a topic by including multiple citations from the reference list upon which you've decided to base your guidelines.  For complicated topics, this allows the developers to see multiple examples and understand the nuances of the issue.  This also has a practical benefit during the authoring and maintenance of your document - you can see where your chosen references overlap and drop any referenced works that don't provide distinctive value.
Discarding content.  Writing code development guidance from established references doesn't come entirely for free despite its "don't re-invent the wheel" benefits.  The problem is that a reference you regularly cite may also include guidance that you don't want followed.  For example, many organizations find it valuable to cite SUN's Code Conventions for the Java Programming Language but find section 5 outdated given it was written in 1999 and the state of software engineering tools widely available today.  Similarly,  you might be frequently citing the Java2 Enterprise Edition (J2EE) Tutorial but not want your developers to follow the sections on EJBs or applets because your organization doesn't use EJBs or applets.
There are several ways to go about excluding guidance from the chosen references and which works best depends upon the scope of what you are using or not using. 
  1. In the reference list.  For the "broad stroke" topics this is the easiest and the cleanest.  If you want to use SUN's Code Conventions as reference but exclude the section on comments, add in the reference list (along with the title, author, publisher, year published, ISBN, etc.) an annotation that you aren't going to use anything from section 5. This works well for outdated material (that you want excluded) and really new material where you haven't made up your mind but don't want people to assume including the reference means you are following everything in it.
  2. As an uncited guidance. This also works well for broad topics.  If your organization doesn't use EJBs, you don't have to exclude everything about EJBs from the books, papers, web-sites, etc. in your references but just add a piece of guidance that says (in effect) "we don't use EJBs" and explains the basic what, why, etc. of this decision. This also works well for very organization-specific practices such as the need to coordinate with another part of your organization or follow some program-specific naming convention.
  3. By explicitly discarding something from a reference.  You might include in your list of references something that you cite repeatedly and generally like but there is one specific thing that won't work in your organization.  Hopefully, you won't have to invest too much effort in this but some topics can be important enough to specifically exclude them.
Resolving Conflicts.  The other inconvenience with drawing from existing published standards is the inevitable conflicts - one reference says one thing and the other reference says another.  Sometimes this can be fairly simple - follow "A" and don't follow "B" - but other times this may require more explanation or some code examples.  This can actually be one of the most beneficial sections of the document because without it developers bring to the project what they know from the general industry and in this case there is contradictory information - that means one developer will do one thing and another will do something else which may spell trouble for the enterprise.  Another way to look at this is that there is no need to cite or reinforce what is already universally agreed upon but that the value of the standard/guideline is to make clear what developers should do for your organization given the uncertainty, controversy, etc. that exists in the industry as a whole on some topic.
Final thought:  As you develop your guidance and standards and winnow out the material from your references that you want to use (or not),  it is a good idea to re-visit the original "by citation" versus "from scratch" approach.  If you find that you can basically write a good standards and guidance document by saying "follow A", "follow B" and "follow C" then this is still a good approach.  If you only have to do a few examples from scratch, this is still a good approach.  However, if you find that you are becoming something of a referee for the works on your reference list (lots of exclusions or lots of "follow this rule and don't follow that rule"), then you are better off reverting back to something closer to the "from scratch" approach.  If that is the case, trying the citation approach hasn't cost you anything - you still have developed the organizational consensus on material.  You can also still re-use lots of material (wording, charts, code examples, etc.) from your references.  What you end up doing is just using the publicly available guidelines less generally and more specifically. 
- Brian    

No comments: