Coding and Documenting - Object Oriented Programming and Data Structures - Lecture Slides, Slides of Object Oriented Programming

Download Coding and Documenting - Object Oriented Programming and Data Structures - Lecture Slides and more Slides Object Oriented Programming in PDF only on Docsity!

Designing, Coding, and

Documenting

Designing and Writing a Program

• Don't sit down at the terminal immediately and start

hacking

• Design stage – THINK first
  • about the data you are working with
  • about the operations you will perform on it
  • about data structures you will use to represent it
  • about how to structure all the parts of your program so as to achieve abstraction and

encapsulation

• Coding stage – code in small bits
  • test as you go
  • understand preconditions and postconditions
  • insert sanity checks (assert statements in Java are good)
  • worry about corner cases
• Use Java API to advantage

Divide and Conquer!

 Break program into manageable parts that can be implemented, tested in isolation  Define interfaces for parts to talk to each other – develop contracts (preconditions, postconditions)  Make sure contracts are obeyed  Clients use interfaces correctly  Implementers implement interfaces correctly (test!)  Key: good interface documentation

Pair Programming

 Work in pairs  Pilot/copilot  pilot codes, copilot watches and makes suggestions  pilot must convince copilot that code works  take turns  Or: work independently on different parts after deciding on an interface  frequent design review  each programmer must convince the other  reduces debugging time  Test everything

Javadoc

• An important Java documentation tool
• Extracts documentation from classes, interfaces
  • Requires properly formatted comments
• Produces browsable, hyperlinked HTML web pages Java source code (many files) Linked HTML web pages javadoc

Some Useful Javadoc Tags

 @return description  Use to describe the return value of the method, if any  E.g., @return the sum of the two intervals  @param parameter-name description  Describes the parameters of the method  E.g., @param i the other interval  @author name  @deprecated reason  @see package.class#member  {@code expression }  Puts expression in code font

Developing and Documenting an ADT

1. Write an overview – purpose of the ADT
2. Decide on a set of supported operations
3. Write a specification for each operation

2. Identify the Operations

• Enough operations for needed tasks
• Avoid unnecessary operations – keep it simple!
  • Don’t include operations that client (without access to internals of class) can implement

3. Writing Method Specifications

• Include
  • Signature: types of method arguments, return type
  • Description of what the method does (abstractly)
• Good description (definitional)
  • /** Add two intervals. The sum of two intervals is
  • • a set of values containing all possible sums of
  • • two values, one from each of the two intervals.
  • */
  • public Interval plus(Interval i);
• Bad description (operational)
  • /** Return a new Interval with lower bound a+i.a,
  • • upper bound b+i.b.
  • */
  • public Interval plus(Interval i); Not abstract, might as well read the code…

Know Your Audience

 Code and specs have a target audience  the programmers who will maintain and use it  Code and specs should be written  With enough documented detail so they can understand it  While avoiding spelling out the obvious  Try it out on the audience when possible  design reviews before coding  code reviews

Consistency

A foolish consistency is the hobgoblin of little minds –

Emerson

• Pick a consistent coding style, stick with it
  • Make your code understandable by “little minds”
• Teams should set common style
• Match style when editing someone else’s code
  • Not just syntax, also design style

Choosing Names

Don’t try to document with variable names Longer is not necessarily better int searchForElement( int[] array_of_elements_to_search, int element_to_look_for); int search(int[] a, int x); Names should be short but suggestive Local variable names should be short

Avoid Copy-and-Paste

• Biggest single source of program errors
  • Bug fixes never reach all the copies
  • Think twice before using edit copy-and-paste function
• Abstract instead of copying!
  • Write many calls to a single function rather than copying the same block of code around

^V