Yao Lirong's Blog

Designing and documenting interfaces and implementations

CS2112
2019/10/17

From Lecture: Designing and documenting interfaces and implementations

An Example of Writing Interface

1. Overview: what concerns?

1
2
/** An n*n mutable 2048 puzzle. */
class Puzzle{}

2. Choose operations

  • creators create objects
    • constructors
    • factory methods (usually static, loose coupling; don’t expose the choice of which class is being constructed)
1
2
public Puzzle(int n){}
   public static Puzzle create(int n){}
  • observers(queries):
    • primary purpose: report the state of object
    • no side effect (doesn’t change anything)
  • mutators (command):
    • primary purpose: side effect on the state of the object
    • only makes sense when the object is mutable
    • should maintain class invariants

Command-Query Separation: You have to decide whether this class belongs to command or query, don’t write both of these things in a single method

Problem with getters:

representation exposure in Mutable Objects (sometimes you directly return the reference to this object and now doing modification to the returned object and unintendedly change the original object)

3. Write Specifications:

  • Returns/Creates: postcondition
  • Requires/Checks: precondition
  • Effects/Modifies: side effects
  • Examples: (as needed)
  • Exceptions: 
     - in return clause: when there is a client error (not programmer error)
       - in checks clause: when precondition violated 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/** Returns: the puzzle size n*/
int size();

/** Effects: adds a random tile to the board*/
void addRandomTile();

/** Effects: adds a random tile to the board
	Returns: true if there was room*/
boolean addRandomTile();

/** Effects: adds a random tile to the board
	Throws: BoardFull if there is no room*/
void addRandomTile() throws BoardFull;

/** Effects: shifts the tiles in direction d*/
void shiftTile(Direction d);

4. Documenting Impls:

Audience: maintainers, not clients

Goals: keep impl details out of the spec (abstraction barrier)

  1. Represents: an abstraction function: concrete fields -> client view

    1
    2
    3
    4
    5
    /** A rational number */
    class Rational {
        int num,dem;
        //Represents: the rational number num/dem
    }

  2. Class Invariant:

  3. Spec for private/protected methods

  4. Algorithms Explanations: (If sometimes the spec is not enough to understand the method(specific algorithm), you should write algorithm explanations inside the method(This would be something client doesn’t have to know but maintainers may want to know so you don’t write them in the spec))

    Write paragraphs instead of interleave comments 

    1
    2
    3
    4
    /** revtrieves the greatest common demoninator of x and y*/
    int gcd(x,y){
        /**This method uses Euclid's to find the ...    */
    }

Author：Yao Lirong

Link：https://yao-lirong.github.io/blog/2019-10-17-Designing-and-documenting-interfaces-and-implementations/

Publish date：October 17th 2019, 12:00:00 am

Update date：June 9th 2022, 3:13:30 am

License：本文采用 Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) 进行许可

CATALOG
  1. 1. An Example of Writing Interface
    1. 1.1. 1. Overview: what concerns?
    2. 1.2. 2. Choose operations
    3. 1.3. 3. Write Specifications:
    4. 1.4. 4. Documenting Impls:
Total : 66
2023
2022
2021
2020
2019
NOI CS2112 Logistics Cornell Review CS3110 Manual Journal Tsinghua Book