From: Garrett Mitchener <wgm2@duke.edu>
  To  : 
  Date: 01 Apr 1999 20:19:37 -0500

Some Java tips

You're going to start a large Java project soon and we're going to try
comment on your Pig code and return it ASAP.  Here are some hints
ahead of time that I know will get people:

* Java has a well-established naming convention that is even part of
  the language spec.  Class source code goes in a file with the same
  name as the class + .java.  Class names should begin with a capital
  letter and have capital letters at word breaks, no underscores:

  public class PigPlayer
  public class ExponentialRandomizer
  public class Dice

  Method names are the same, except that the first letter is lower
  case:
 
  public void doStuff()
  public String getName()

  Method names that just get or set one piece of data should begin
  with get or set, which is a convention used by Java beans:

  public String getName()
  public void setTitle( String newTitle )

  C++ style is fairly flexible for historical reasons.  Java is *much*
  less so.  You should write your code thinking that it will be made
  distributable and reusable, and other people will expect it to
  follow these conventions.  Plus, it makes us much happier when we
  grade your projects.

  Indentation and placement of braces {} in Java is not as strict as
  naming, since all that is hidden in your source code.  It's the
  interface that matters most.

* Do use the "my" convention in which you prefix every data member in
  a class with "my".  This is mostly a 108 thing but it is common
  practice in lots of places to put a "wart" on data members to make
  them easy to distinguish from local variables.  Other common ones
  are an "m_" prefix or an "_" prefix or postfix, but in 108, we
  prefer my, and the rest of the name is capitalized like a method.
  For static data, use an "our" prefix.  I personally also use "im"
  (for "I'm") on boolean variables, as in imDone, but it is arguably
  better to use "myIsDone" instead.  This goes for C++ and Java.  I do
  not recommend Hungarian notation where you attach warts that reveal
  the whole type of the variable, because you're in trouble if you
  need to change that type.

* For constants, use all capital letters and "_" in between words:

  public final int NUMBER_OF_SIDES = 6;

* Use javadoc.  We tried to get a similar documentation thing going
  for C++ but it didn't work out.  Again, C++ has no single standard.
  In Java, almost all documentation comes from javadoc.  Get in the
  habit of carefully commenting the purpose and behavior of each class
  and public or protected method.  Use the special comment format, and
  before you submit anything, run javadoc on all your source code.  It
  will extract your comments and make very nice web pages.  You may
  want to post your javadoc to a group web page every so often so
  all members in your group can reference it.

* Use interfaces.  Unless you know for certain that you need an
  abstract class, make it an interface.  The nice thing about
  interfaces is that a class can implement (inherit) from any number
  of them.  Java only allows a class to have one superclass.

  Why is this so important?  Imagine that you're writing for the
  adventure game assignment that just went out.  You want to have
  "GameObjects" that have certain behavior, and inherit class Player,
  Room, etc. from class GameObject.  Now suppose someone has given you
  a Graph class that can hold objects that inherit from class
  GraphObject.  You would like to model your maze with a Graph object,
  but now you have to jump through a lot of hoops to put a Room into a
  graph, because class Room is derived from class GraphObject.  You
  could sort of solve the problem by making GameObject inherit from
  GraphObject, but that may mess up class Sword because there may be
  no way to give a sword enough behavior to make it a GraphObject.

  The best alternative is to make GraphObject and possibly GameObject
  interfaces instead of classes.  Then, the problem disappears.

  My personal rule of thumb is that I always write just about
  everything in terms of interfaces.  Then, if I can come up with an
  abstract base class that can provide a lot of default functionality,
  I write that class and have it extend some interface, write
  subclasses, etc. and I will have lost nothing other than the little
  bit of time it took to write that interface.  Note that this is a
  rule of thumb -- Don't just do it in your program, say "I did it
  because someone said I should on the newsgroup."  Think about it
  carefully, decide why you should or shouldn't do it, and document
  that decision in your project.

  Point of confusion: interface source code follows the same file
  conventions as classes.  You put it in a file with the same name as
  the interface + .java, and when you compile it, you get a .class
  file.  Java stores both compiled classes and interfaces in .class
  files.


If you have questions about these suggestions, post to the newsgroup,
bring them up in class, or come to office hours.

	-- Garrett :-)