Comments: 5.3.1

  • comments make code more readable and maintainable
  • allows you to explain things for when you come back to them later
  • 3 types of comments
    • Single line comment
      • Uses special characters //
    • multiline comment
    • documentation comment
      • useful with the javadoc tool
      • turns these comments into documentation as a webpage
  • the compiler will skip over comments
    • they don’t effect how the program runs
  • there are some tags which are useful in comments
    • Not required
    • @author program author
    • @since date released
    • @version version of the program
    • @param parameter of a method
    • @return return value of a method
// single line comment
/* multi
line
comment */

/** documentation
comment
@param foo
*/
void myMethod(String foo)

Preconditions and Postconditions: 5.3.2

  • as you write methods, keep in mind the preconditions and postconditions
    • a precondition is a condition which must be true for your method to work
      • all objects mustn’t be null
      • methods can check for preconditions, but that isn’t needed
    • a postcondition is a condition which is true after running a method
      • what a method should do
      • describes the outcome
        • what the return type is
        • how it modifies an object’s internal state

public class House {
  private String paintColor;

  /**
   * Sets the value of color
   * 
   * Preconditions: c is not null
   *
   * Postconditions: the house color will be set
   */
  public void setPaintColor(Color c) {
    paintColor = c.toString();
  }
}

Software validity and Use-case diagrams: 5.3.3

  • Determining pre/postconditions help to test code and determine the validity of a program
    • tests whether the software does what it’s supposed to
  • try to break your code!
    • try all kinds of inputs to find edge cases
  • create use-case diagrams of a system to show how a user might interact with a program
    • a use-case is a particular interaction with a software
      • often become methods in a program
    • after creating a diagram, programmers write down preconditions and postconditions

Agile software development: 5.3.4

  • there are many models for software development
    • waterfall model
      • developed in the 1970s
      • requirements -> design -> implementation -> verification -> maintenance
      • completed linearly
      • criticized for not being very adaptable
    • Agile development
      • Iterative and incremental
      • teams work in 2-3 week sprints
        • completely develop, test, and release a component
          • should be ready to ship
        • receive customer feedback
        • adaptable

Summary: 5.3.6

  • comments are ignored by the compiler and are not executed when the program runs
  • 3 types of comments
    • /**/ block comments
    • // line comment
    • /** */ javadoc comments
  • A precondition is a condition which needs to be true for the execution of a section of code to behave as expected
    • there is no expectation that this needs to be checked in the program
  • a postcondition is the condition that must be true after the execution of a section of code
    • describe the outcome of execution
      • what is returned
      • the internal state of an object
  • programmers write method code to satisfy postconditions for a given precondition