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 comments while (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 city has 1 possible ordering 2 cities have 2 3 cities have 6 4 cities have 24 n cities have n! This is a hard problem its difficulty of solution is O(n!) (we can reduce this by 2 by symmetry) 4 5

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

A Silly Comparison of Methods Hill climbing is like dropping a kangaroo somewhere on the surface of the earth, telling it to only hop uphill and hoping it will get 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 of kangaroos 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