C Programming (the Final Lecture)

• How to document your code.

• The famous travelling salesman problem (and when a problem is _really_ hard).

• Three ways to "solve" any optimisation (using kangaroos).

Types of documentation

• Internal documentation (comments in your code)

• External programmer documentation (for other programmers who would work with your code)

• User documentation (the manual for the poor fools who will be using your code)

How to write good comments

• Does your comment help your reader understand the code?

• Are you writing a comment just because you know that "comments are good"?

• Is the comment something that the reader could easily work out for themselves?

• Don't be afraid to add a reference instead of a comment for tricky things

Some common bad comments

i= i+1; /* Add one to i */

for (i= 0; i < 1000; i++) { /* Tricky bit */.. Hundreds of lines of obscure uncommented code here .}int x,y,q3,z4; /* Define some variables */

int main()/* Main routine */

while (i < 7) { /*This comment carries on and on */

How comments can make code worse

while (j < ARRAYLEN) { printf ("J is %d\n", j); for (i= 0; i < MAXLEN; i++) { for (k= 0; k < KPOS; k++) { printf ("%d %d\n",i,k); } } j++;}

Some more bad commentswhile (j < ARRAYLEN) { printf ("J is %d\n", j); for (i= 0; i < MAXLEN; i++) {/* These comments only */ for (k= 0; k < KPOS; k++) {/* Serve to break up */ printf ("%d %d\n",i,k);/* the program */ }/* And make the indentation */ }/* Very hard for the programmer to see */ j++;}

How much to comment?

• Just because comments are good doesn't mean that you should comment every line.

• Too many comments make your code hard to read.

• Too few comments make your code hard to understand.

• Comment only where you couldn't trivially understand what was going on by looking at the code for a minute or so.

What should I always comment• Every file (if you do multi-file programming) to

say what it contains• Every function – what variables does it take and

what does it return. (I like to comment the prototypes too slightly to give a hint)

• Every variable apart from "obvious" ones (i,j,k for loops and FILE *fptr don't require a comment but int total; might)

• Every struct/typedef (unless it's really trivial)

Other rules for comments

• Comment if you do something "weird" that might fool other programmers.

• If a comment is getting long consider referring to other text instead

• Don't let comments interfere with how the code looks (e.g. make indentation hard to find)

External (programmer) documentation

• This tells other programmers what your code does• Most large companies have their own standards

for doing this• The aim is to allow another programmer to use

and modify your code without having to read and understand every line

• I would hope that your projects will include this type of documentation

• This is just ONE way of doing it – everyone has their own rules.

External documentation (Stage 1)

• Describe how your code works generally

• What is it supposed to do?

• What files does it read from or write to?

• What does it assume about the input?

• What algorithms does it use

External Documentation (stage 2)

• Describe the general flow of your program (no real need for a flowchart though)

• Diagrams can help here.

• Explain any complex algorithms which your program uses or refer to explanations elsewhere. (e.g. "I use the vcomplexsort see Knuth page 45 for more details")

External documentation(stage 3)

• If you use multi-file programming explain what each file contains

• Explain any struct which is used a lot in your program

• You might also like to explain (and justify) any global variables you have chosen to use

External documentation (stage 4)

• Describe every "major" function in your program• Describe what arguments must be passed and what

is returned.• (It is up to you to decide what is a "major"

function – and really depends on the level of detail you wish to document to).

• Consider which functions are doing "the real work" – they might not necessarily be the longest or most difficult to write ones.

User documentation

• This is documentation for the user of your program

• It is the "user manual"• Entire books have been written on the

subject and I don't intend to cover it here• Feel free to include user documentation for

your project if you want (but not too much of it)

Optimisation (the travelling salesman)

• The travelling salesman problem is a classic optimisation problem. A salesman must visit all of 'n' cities in the shortest possible time.

1

2

3

1 city has 1 possible ordering2 cities have 23 cities have 64 cities have 24n cities have n!This is a hard problem its difficulty of solution is O(n!)(we can reduce this by 2 by symmetry)

45

What's the point of this silly problem?

• The TSP represents a class of problems known as NP-hard.

• This means that no known solution to the problem arrives at a solution in polynomial time

• NP-hard problems are computationally equivalent - a solution to one is a solution to all. Solving (or proving the non-existence of a solution) of NP-hard problems is one of the famous "10 most important problems in maths" – with a $1m prize.

So how do we solve this?• We cannot use "brute force and ignorance" to solve

this problem. There are simply too many combinations. We must be cleverer.

• Irritatingly, this type of "hard" optimisation problem is extremely common in computing

• There are three commonly used ways to get an approximate solution:– Hill Climbing– Simulated Annealing– Genetic Algorithms

Hill Climbing• To visualise hill climbing, imagine our problem

space is a landscape and we wish to reach the highest point.

• Starting with a random solution we can either:– Find an ascent direction and move a small amount in

that direction– or Keep picking random directions until we find one

which is an improvement

• Repeat until no improvement can be found.

Hill Climbing (2)• In the case of the travelling salesman problem we

might pick a solution at random and then swap the order of one city in the route until no further swaps produce improvement

• Pros:– Computationally simple

– Fast to run

• Cons:– Gets stuck in local maxima

Simulated Annealing• Simulated annealing is based upon a physics

analogy - crystal formation in metals

• We set a temperature variable

• As with hill climbing, we pick some "direction" to take steps in.

• Unlike with hill climbing, we might choose to move "down-hill" if the temperature is high.

Simulated Annealing (2)• By gradually lowering the "temperature" we

eventually move from allowing wild jumps across the landscape to becoming more like a hill-climbing process.

• Pros:– Avoids some local minima.

– Only a little more computationally intensive.

• Cons:– A random process - doesn't guarantee a good solution every

time

Genetic Algorithms• Begin by producing a whole bunch of random

solutions.• Let our selection of solutions "breed" by producing

hybrid solutions by mixing them.• Mutate solutions by randomly swapping parts of them.• Occasionally kill off some of the solutions which are

less optimal.• By a process of killing some of the worst solutions the

best solutions "survive" and "breed"

Genetic Algorithms (2)

• Works like "evolution" to produce good solutions• Pros:

– Not very susceptible to local minima.

– Likely to find good solutions for many problems.

• Cons:– Computationally both difficult and slow.

– Doesn't work for every problem.

A sensible comparison of the methods

HillClimb

SimAnneal

Gen.Alg

Comp.Effort

Low Low(ish)

High

Deals w.local max

No Sort of Yes

Guaranteedsolution

Localmax

Localmax

None

A Silly Comparison of Methods

Hill climbing is like dropping a kangaroo somewhere on thesurface of the earth, telling it to only hop uphill and hoping it willget to the top of mount Everest.

A Silly Comparison of Methods

Simulated Annealing is like doing the same but getting the kangaroo very very drunk first.

hic

A Silly Comparison of Methods

Genetic Algorithms are like taking a whole plane load ofkangaroos and letting them reproduce freely (not pictured).....

A Silly Comparison of Methods

....and regularly shooting the ones at lower altitudes.

Aaaargh! Ouch

That’s all

• You have now learnt the C programming language

• How to document and test your code

• Some simple algorithms to solve general problems

• The rest is just practice...

No kangaroos were harmed in the making of this lecture