Some conventions for code

• Comment your code so that you and others will know what it does and how it works.
  • Use javadoc style for comments that you would like to appear in the documentation generated by javadoc
    • Before each class, constructor, and method definition and before each field declaration, include a comment between /** and */. You can include HTML tags in the comments.

      /**
       * This class variable represents the number of actions that all
       * Critters can take.
       */
      public static int nActions;
      

    • Among the keywords that have special significance within javadoc comments are @param and @return.

      /**
       * Causes the Critter to either move or turn with the given probability.
       * @param turnAngle The clockwise angle (1-5) to turn.
       * @param turnProbability The probability of turning.
       * @return Reinforcement received.
       */
      public int moveOrTurn(int turnAngle, double turnProbability) {
          return getWorld().moveOrTurn(getCritter(), turnAngle, turnProbability);
      }
      

    • To generate documentation do javadoc followed by the names of the source (.java) files that you want to document. If you want the documentation to go to a different directory, use the -d option. For example

      javadoc -d Docs/ Smarts.java Brain.java Effector.java Sensor.java
      

  • For comments within a method or constructor, use //. Everything following this one a given line will be treated as a comment.
• Indent your code properly. Most editors will do this automatically (see the "Preferences" for XCode) or when you tab a line that you want to indent.
• Put your name at the top of every source file.

© 2004. Indiana University and Michael Gasser. www.indiana.edu/~gasser/Q530/Notes/code.html 4 Oct 2004