Documentation

Your documentation must fit the needs of your audience.

It’s always better to say one thing that is useful, as opposed to many things that are not.

Worse Than Useless

/* * Gets the serial number */public int getSerialNumber()

What does this mean?

/* * Gets the old number */public int getSerialNumber()• The old number is the serial number• There are actually 2 serial numbers – this is the old one• I copied this from the function get old number, but I

forgot to change the comment• This gets the serial number, but if the number is

changed it might actually be old and not updated

First rule of thumb

If you want to write a comment, your function is named wrong or your code is not well structured.

doMatrixMultiply(double a1, double b1, double c1, double d1, double e1, double f1, double g1, double h1, double i1, double a2, double b2, double c2, double d2, double e2, double f2, double g2, double h2, double i2)

Second rule of thumb

• Documentation that is out of data is far worse than useless

• Use stuff like JavaDoc, and make sure your javadoc gets updated automatically

So basically you never have to write any documentation ever, and your Software

Engineering professor said it was good style, right?

Two Kinds of Documentation You Will Have to Write

• Explanatory documentation“Oh my god this system has 65 classes in it. How do I

make it do what I want? Surely it doesn’t have to be so complicated.”

• Persuasive documentation“Why should I use your silly design when in 1 minute,

I already thought of a really simple clean design that solves every use case I can immediately envision?”

Here’s where the magic happens:A explanation of the class.

A tiny, yet explanatory code example

All laser-focused on answering the question “I want to get this code working NOW. What do I do?”

Details when they are needed

/* This function gets the serial number. The number is an integer between 1 and MAXINT but in practice is a number between 1000 and 2500. Blah blah blah blah. */

public int getSerialNumber() {

/* Sets DB consistency flag */public void setDBConsistencyFlag(char f) throws DBModularityMismatchException

Java’s Comparable Interface

• Write the sample code you would like to see if you were writing the documentation for Java’s comparable interface

• Keep in mind the point is not to say “well it has one function compareTo”. The point is to use an explanatory example that shows Comparable in use.

public class Rectangle implements Comparable<Rectangle>{ private int myWidth; private int myHeight; public Rectangle(int width, int height) { myWidth = width; myHeight = height; }

public int compareTo(Rectangle other) { int myArea = myWidth*myHeight; int otherArea = other.myWidth * other.myHeight; if(myArea < otherArea) return -1; if(myArea > otherArea) return 1; return 0; // I could also just say // return myArea - otherArea } public static void sortRectangleArray(Rectangle[] input) { //implictly calls compareTo //sorts Retangles by area, smallest to largest Arrays.sort(input); }}

Explanatory Documentation

• Focuses on explaining at a high level• Provides sample code for getting started fast• Knows that every detail can’t be explained –

relies on the programmer to do some code-exploration on their own

• BUT you should explain the really hard parts of the code

Your Teams Overall Final Design Submission should be Explanatory Documentation

• We’ll be looking for what developers usually look for initially: that the design provides many useful features yet is easy to use

• Clear concise sample code is good• UML Diagrams too• You need to explain your design, but you can assume your

audience understands sophisticated OO terminology• A good heading “How to make a functional <genre> game in

15 minutes”

Two Kinds of Documentation You Will Have to Write

• Explanatory documentation“Oh my god this system has 65 classes in it. How do I

make it do what I want? Surely it doesn’t have to be so complicated.”

• Persuasive documentation“Why should I use your silly design when in 1 minute,

I already thought of a really simple clean design that solves every use case I can immediately envision?”

Thing You Absolutely Need• What You Are Solving• What the challenging parts of what your are solving are

– What you want to be easySpecifying what parts of fighting character should be considered to deal damage

– What you want to be pretty easyMaking the parts move as the attack animation progressesHaving simple rules for which attacks beat which other attacksVisualizing what parts are damage dealing in the level editor

– What you want to be possibleHaving complicated rules for which attacks beat other attacksAdding new region types

• This is what you want to be especially good in the doc you’re submitting on Monday, and it’ll make up the first section of your final design doc

One Technique: A Sample Use Case

• Select 1 or 2 examples that will run throughout your document (often one pretty simple one, one pretty complex one)

• Initially, they serve as examples of complex problems

• As you continue, they become showpieces for your improved code

The Design Itself

• Clarity of explanation is most important – the “persuasive” should come pretty naturally

• Example code that shows how the design ought be used

• If there’s some pretty tricky code, maybe just a bit of code on how the design is implemented

• Diagrams, maybe several, maybe several types

“Sketch” A Solution

• For the first doc, I request you present a proposed solution

• It doesn’t need to be perfect, but you should give it some thought. It will be a starting point for the discussions you and your TA will be having

Design Alternatives

• Not required for this week’s submission, but is required in final submission

• Need to be genuine alternatives – oftentimes you can judge the quality of the design itself by looking at what the author considered alternatives

Things to avoid

• Making your persuasive document into a narrative (e.g. “originally our system was built like X but that had some problems”)

• Bringing up irrelevant details because your problem is not complex enough

• Leaving diagrams till the end, instead of placing them near the system you’re describing so I can refer to them as I read