- instantiable class: class that we can create instances of
- won't be able to use predefined classes for all needs
- design own class
  - specify class
    - how we interact with the class and its instances
    - what kinds of instance and class methods the class should support
    - use it in a way that is natural and logical
    - always consider alternative designs
      - relative merit depends on how the class is used in programs
      - use design guidelines
        - e.g., keep the class simple
- template for designing a class: p. 153
- data members
  - data values for the class
  - include class and instance variables and constants
- modern abundance of memory means unnecessary to use float instead of double to save space
  - conventional to use double (preferred)
- javadoc comments
  - begin marker: /**
  - end marker */
  - asterisks on the lines between the first and last markers
    - no significance
    - provide visual to highlight the comments
    - accepted standard
  - javadoc tags: special markers that begin with the @ mark
    - @author: use to list the author(s) of the class
- instance variable / instance data value
  - declared within the class declartion
  - declared outside any method of the class
  - every object of the class will have its own copy; diagram: p. 155
- visibility modifier: specifies the visibility/accessibility of the data members and methods
  - reserved words
  - e.g. private, public
- method definition syntax:
  <modifiers> <return type> <method name> ( <parameters> ) {
      <statements>
  }
- void return type
  - method returns no value
- static modifier
  - designates a class method
    - cannot access instance variables
    - can only access class variables and constants
  - methods without the static modifier are instance methods
    - access class variables and constants as well as instance variables and constants
- define how instances of the class will behave
  - mostly defining instance methods
- public
  - visibility modifier
  - designates a method as accessable from outside methods
- outside methods: methods that belong to different classes are outside methods to each other
- private
  - visibility modifier that means a method cannot be called from outside the class
- class documentation
  - method header comment: one for every method; describes the method
    - record the method's purpose
    - list of parameters
    - short description of each parameter
      - syntax: @param <parameter name> <description>
      - description can be multiple lines
    - document return value, if any
      - syntax: @return <description>
- value-returning method/non-void method: includes a return statement with the syntax: return <expression>;
- void method optionally includes return statement with the syntax: return;
- use parentheses in the reutrn statement to delineate the expression part clearly
- class-listing convention
  class <class name> {
      // data members

      // public methods
      
      // private methods
  }
  - list each group of methods in alphabetical order
  - provide a block comment for each group of methods
    - quick reference to the methods in the group
      //--------------------------------------------------
      // <group type> Methods:
      //
      // <return type> <method name> ( <parameter types> )
      //
      //--------------------------------------------------
    - not needed by the javadoc generator
    - so programmers reading the program will have a handy reference without referring to the online documentation
    - javadoc comments are used only for describing the class and its data members and methods
  - Java compiler does not care about the order of methods and data members
  - convention is to make it easier for us to follow

Quick Check:
1.  It declares the return type void, but then tries to return an expression.
2.  one and three are class methods
3.  /**
     * This class provides an interface for naming students.
     *
     * @author Michelle Moravan
     */

    class Student {

    //------------------------------------------------------
    // Data Members
    //------------------------------------------------------
        /**
         * The student's name
         */
        private String name;
    //------------------------------------------------------
    //    Public Methods:
    //
    //        void   assign   ( String )
    //        String identify (        )
    //
    //-------------------------------------------------------
        /**
         * Changes the student's name
         *
         * @param newName the student's new name
         *
         */
        public void assign(String newName) {
            name = newName;
        }

        //**
          * Retrieves the student's name
          *
          * @return name of the student
          *
          */
        public String identify() {
            return name;
        }

    }