Lecture Notes for Advanced Programming II

4 September 2003 - How to Pass This Course

What Happened Last Time

Course Objective

The course objective is to turn you into good programmers.
Good programmers, among other things, write good programs.
- They also design, trade-off, learn new things, review old things, ...
Good programs
- do the job they're supposed to do.
- handle incorrect input.
- never ever crash for internal reasons.
- are easy to understand.
- are easy to modify.

Be a Good Student

Follow directions.
Exhibit learning behavior.
- Mistakes
Schedule your time wisely.
Work in groups.
Ask good questions.

Follow Directions

Testing is automated.
If you don't follow directions, your tests will fail and so will you.
Input
- Understand std-in, std-out, and command-line arguments.
- Do not prompt for input.
- If the assignment has "read from std-in" then your program should read from std-in.
  - Do not read from a file.
Do you want to deal with someone who can't follow directions?

Output

Follow the output format.

Specified:
Output rectangles one per line with the format x₁ y₁ x x₂ y₂.

Implemented:

THIS SI FINAL DISPLAY OF AN ARRAY 
{[ 1, 1 ], [ 3, 3 ]}  Level is : 0 Position is : 0
{[ 2, 2 ], [ 4, 4 ]}  Level is : 1 Position is : 0

Debugging output.
- Send debugging output to std-err (cerr).
- Turn off debugging output in submissions.
Testing is automated.

Exhibit Learning Behavior

Penalties increase as time goes on.
- The penalty for buffer-overflow errors grows quickly.
- The penalty for old errors grow quickly.
Frowned upon behavior should decrease over time.
If you read about it, and we talk about it, I should see it in your code.
For example: including .cc files.
```
#include "my-list.cc"
```
- Unconventional, screws up compilation.
- The first time I may rewrite it.
- The second time it'll loose points.

"But Everybody Makes Mistakes."

That's true, expected, and important.
But, make mistakes where it doesn't hurt you.
- Making mistakes when you enter book programs is good.
- Making mistakes when you study with friends is good.
- Making mistakes on tests is bad.
- Making mistakes in assignments is bad.
It's like music - you make mistakes, but not on stage.
Exhibit learning behavior.
The road to wisdom?
Well it's plain and simple to express:
err and err and err again
but less and less and less.
---- Piet Hein

Use Your Time Wisely

Make sure you schedule your time wisely.

Date: 14 Dec 2001 13:41:19 -0500
From: "R. Clayton" <rclayton@monmouth.edu>
To: s0------@monmouth.edu
Subject: Re: assignment 7

  Since these are the final days of the semester, 
  every deadline seems to come together at once. 
  Could we have an extension for the final assignment 
  for CS-509.

Sorry, no deadline extensions.

I generally don't extend individual deadlines.

Date: 29 Oct 2001 11:29:37 -0500
From: "R. Clayton" <rclayton@monmouth.edu>
To: s0------@monmouth.edu
Subject: Assignment deadline.

  I've had a report, a project, a mid-term test 
  and your assignment due this week.  Can I get an 
  extension on the assignment?

No, sorry - no extensions.

No, Really - Use Your Time Wisely

Date: 6 Mar 2003 16:36:14 -0500
From: "R. Clayton" 
To: s0------@monmouth.edu
Subject: Deadline extension

  Is it possible to postpone the project due
  date by a couple of days? All the school
  labs are closed from Friday 5 pm to Monday
  morning, and some of us don't have
  computers at home.

Because you've been working on this project
for the past three and a half weeks, I'm
disinclined to extend the deadline.  What
you've accomplished up to this point should
be more than enough to do well in the
project; the bells and whistles you could add
in the remaining days, although they may be
interesting, are probably not important in
meeting the project's requirements.

Learn to Ask Questions

It's imperative you learn how to ask good questions.
- You're going to have to ask questions anyway.
- An intelligent question is the mark of an intelligent person.
- Bad or stupid questions quickly alienate your colleagues.
Good questions are
- Complete - what's the problem?
- Suggestive - you tried to solve it yourself.
- Through - provide all relevant information.

Other Bits of Advice

Design before you implement.
- Know what you're implementing.
Work in groups of two or three.
- Design and evaluate the design.
- Implement alone.
- Test the implementation.
Go back and review.
- You're learning new things - how do they help?
- You're going to be seeing your mistakes again.
- It's like music: practice makes perfect.

Be a Good Programmer

You're going to be a professional - act like one.
Programming is communication.
Know your tools.
Test your code.
Documentation.

Programming is Communication

Your program communicates with other people.
- The people who maintain and modify your code.
- Yourself three months from now.
Your code is talking about you.
- What does your code say about you?
- Is it saying your stupid or smart?
Learn to recognize badly written code.
- And run away from it (or burn it and start over).
- This is also known as code smells.

Know Your Tools

Stream I-O.

Don't duplicate function.

What is going on here?


void eat_white() {
  while (cin && isspace(cin.peek()))
  cin.ignore();
  }

void f() {
  while(cin && (cin.peek() != EOF)) {
    cin >> s;
    eat_white();
    }
  }

Understand error and exceptional conditions.
- Understand and use correctly the end-of-file condition.

Know your libraries.
- Unix has a lot of them, and they are here to help you.
- C++ libraries can get complicated (stream io).

Test Your Code

Don't rely on only my tests.
Work in teams, test each other's code.
Important for those programming on other systems.
- Microsoft is more forgiving (read "non-standard") than is Solaris.
- Disable Microsoft extensions; use strict ANSI-ISO compatibility.
Code that core dumps loses big points.
- Your program should handle empty input properly.
  - $ program < /dev/null
- Your program should handle garbage input properly.
  - $ program < program
- "Properly" means without core dumping.

The Vexing Question of Documentation

Document your programs and code.
- What are you trying to do?
- How are you trying to do it?
Make sure your comments are helpful.
- Bad:
```
// main function
int main() {

count = 0; // make counter to zero

// Break the loop if temp_sum >= sum_of_vec

while (temp_sum < sum_of_vec) {
```
- Better:
```
// Find the largest sub-sum less than the total.

while (temp_sum < sum_of_vec) {
```
My Documentation Style
- I prefer a minimial documentation style.
- Write short, complete comments for files and code.
  - // Represent expressions as binary trees.
  - // Insert the constant value n into the tree.
- Emphasize purpose, not method.
  - Purpose should be simple, complete, and correct.
  - Method should be obvious from the code.
  - But, tricky methods should be documented.
- Documentation is a coding clue.
  - If you can't write a short, complete sentence
    your code's probably not well written.
Functional Documentation
- Functional documentation provides an input-output description of a function.
  - Input: parameters and globals.
  - Output: return value, reference parameters, and globals.
  - Input-Output: the transformation the function performs between input and output.
- Documenting a functions innards isn't necessary.
  - If it's tricky code you may want to.
  - If it's small you don't need to.
- Pay attention to your documentation.
  - Is it complete? If not, your function may be too complex.
  - Is it big? If so, your function may be too complex.
    - If your documentation is bigger than your function body, you've got a problem.
Functional Documentation Examples
- Poor.
```
unsigned check(unsigned n) { ... }
```
  Check what? For what? And then what?
- Fair.
```
// Function to check if the number is Prime

unsigned IsPrime(unsigned Pnum) { ... }
```
  O.k., check if (I guess) Pnum is prime. Then what?
  We're not playing 20 questions; we're communicating.
- Good.
```
bool IsPrime(unsigned n) {
  // Return true iff n is prime.
  }
```
Functional Comments and Grading
- Every function without a comment is going to cost you a point.
  - Every function.
- Every function without a good comment is going to cost you a point.
  - A good comment
    - Describes every input.
    - Describes every output.
    - Describes what happens between input and output.
General Programming Tips
- Dynamic memory - don't don't do it.
- Code size.
- Duplicate code is bad code.
- No magic numbers.
Dynamic Memory is Not Your Friend
- Make sure you need it.
```
char *temp = new char[5];
strcpy(temp,"<FONT");
char *temp2 = new char[5];
```
- If you do need it, use it correctly.
```
bool readInst(List *L, char *&inst, int noInst) {

  char * line = new char[80];
  inst = new char[80];
  strcpy(inst, "\0");

  line = L->getNext();
  if ( line  == NULL )
    inst = NULL;
    return false;
  }
```
- If you allocate it, free it.
  - Falling of the end of main() is not freeing storage.
- I'll be watching.
  - Programs are tested with limited amounts of storage.
  - Programs are tested with debugging storage allocators.
Big Code is Bad Code
- Big code (big functions, big programs) are trouble.
  - Hard to understand.
  - Hard to create.
  - Hard to maintain.
- You are responsible for every line of code you write.
  - Every array access, every pointer reference, all of it.
  - The less you write, the smaller your responsibility.
- My rules of thumb.
  - More than 25 lines is a big procedure.
  - More than 10 procedures is a big file.
  - File count doesn't matter.
Write Small Code
- For example.
```
void main() {
  LList list;

  cout << "Please enter a sequence of sets of "
       << "algebraic eq. (ctrl+d) to end" << endl;

  int setCount = readInput(list);
  printResults(list, setCount);
  }
```
  or
Code Size and Grading
- Every function containing more than 30 code semicolons will cost you a point for every five over.
  - Rounded up.
- Example: a function contains 42 code semicolons.
  - ceiling((42 - 30)/5) = 3 points off.
- A handy rule of thumb:
  Don't have more than 25 statement lines in a function.
Avoid Duplicate Code
- Duplicate code is bad code.
  - It's hard to change.
  - It causes code bloat.
  - It's hard to understand. (Is it really duplicate?)
```
bool alpha_test(vector < string > vect)
  if (vect[0] == "move")
    if (vect[1] == "r0" || vect[1] == "r1" || vect[1] == "r2" ||
        vect[1] == "r3" || vect[1] == "r4" || vect[1] == "r5" ||
        vect[1] == "r6" || vect[1] == "r7") {

      if (vect[2] == " r0" || vect[2] == "r1" || vect[2] == " r2" ||
          vect[2] == "r3" || vect[2] == "r4"||vect[2] == "r5" ||
          vect[2] == "r6" || vect[2] == "r7") {  }

        if (vect[2] == "r0" || vect[2] == "r1" || vect[2] == "r2" ||
            vect[2] == "r3" || vect[2] == "r4" || vect[2] == "r5" ||
            vect[2] == "r6" || vect[2] == "r7" ) { }

bool move_test(vector < string > vect )
  if (vect[0]!="move")
    for (unsigned int k = 1; k < vect.size();k++)
      if (vect[k] == "r0" || vect[k] == "r1" || vect[k] == "r2" ||
          vect[k] == "r3" || vect[k] == "r4" || vect[k] == "r5" ||
          vect[k] == "r6" || vect[k] == "r7") {  }
```
- Put duplicate code in a procedure and call the procedure.
No Magic Numbers
- A magic number just appears in code with no explanation.
  - What does this code do?
```
int ans = check(s.substr(i,j-i));
     if (ans == 1) { /* whatever */ }
else if (ans == 2) { /* whatever */ }
else if (ans == 3) { /* whatever */ }
else if (ans == 4) { /* whatever */ }
else if (ans == 5) { /* whatever */ }
else if (ans == 6) { /* whatever */ }
else if (ans == 0) return false;
```
- Magic numbers are hard to understand, use, and change. Avoid them.
```
char ch[200]
while cin.getline(ch, 200, '\n')
  ...
  f(200)
  ...
```
  Have you changed all proper values?
  Have you left alone all other values?
Use Named Constants
- Replace magic numbers with named constants.
```
#define INVALID  0
#define NUMBER   1
#define VARIABLE 2
#define OPERATOR 3
#define LB       4
#define RB       5
#define EQUAL    6

if (StBlk[row][0].Type() != VARIABLE) /*...*/
if (StBlk[row][col].Type() == INVALID) /*...*/
if ((StBlk[row][col].Type() == NUMBER ||
     StBlk[row][col].Type() == VARIABLE) &&
    (StBlk[row][col+1].Type() == LB)) /*...*/
if (StBlk[row][col].Type() == EQUAL) /*...*/
if (StBlk[row][1] .Type() != EQUAL) /*...*/
```
- Better
```
const int 
  INVALID  = 0,
  NUMBER   = 1,
  VARIABLE = 2,
  OPERATOR = 3,
  LB       = 4,
  RB       = 5,
  EQUAL    = 6;
```
Other Programming Tips
- Don't use system().
  - It is dangerous, unreliable, and expensive.
  - system() will be broken for testing.
- Don't abuse files.
  - They are unreliable and expensive.
  - Files will be limited for testing.
- Avoid dynamic memory; use dynamic memory correctly.
- You are responsible for every array access.
  - A[-1] is never correct.
  - Neither is A[4294967295].
- I'll be checking your container accesses too.
  - Use the Safer STL library.
This page last modified on 4 September 2003.