C Programming (the Final Lecture)

1. 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).

2. 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)

3. 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

4. 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 */

5. 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++; }

6. 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++; }

7. 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.

8. 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)

9. 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)

10. 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.

11. 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

12. 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")

13. 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

14. 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.

15. 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)

16. 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 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) 2 5 1 4 3

17. 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.

18. 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

19. 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.

20. 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

21. 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.

22. 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

23. 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"

24. 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.

25. A sensible comparison of the methods

26. 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.

27. A Silly Comparison of Methods hic Simulated Annealing is like doing the same but getting the kangaroo very very drunk first.

28. A Silly Comparison of Methods Genetic Algorithms are like taking a whole plane load of kangaroos and letting them reproduce freely (not pictured).....

29. A Silly Comparison of Methods Aaaargh! Ouch ....and regularly shooting the ones at lower altitudes.

30. 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