C Programming - Lecture 7 This lecture we will learn: –How to write documentation. Internal docs. External docs. User docs. (But not much about this). –More about linked lists. –Binary Trees.

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)

Address book with linked lists typedef struct list { char name[MAXLEN]; char address[MAXLEN]; char phone[MAXLEN]; struct list *next; } ADDRESS; ADDRESS *hol= NULL; /* Set the head of the list */

Linked list concepts NULL head of list Adding an item to the middle of the list NULL head of list new item points at next item move this link Deleting an item from the middle of the list NULL head of list move this link delete this node

Adding to our address book void add_to_list (void) /* Add a new name to our address book */ { ADDRESS *new_name; new_name= (ADDRESS *)malloc (sizeof (ADDRESS)); /* CHECK THE MEMORY! */ printf ("Name> "); fgets (new_name->name, MAXLEN, stdin); printf ("Address> "); fgets (new_name->address, MAXLEN, stdin); printf ("Tel> "); fgets (new_name->phone, MAXLEN, stdin); /* Chain the new item into the list */ new_name->next= hol; hol= new_name; }

The Binary Tree A binary tree is a method for storing ordered data (for example a dictionary of words) where we wish to easily be able to add items and find items Each element in the tree can lead to two further elements – to the left and to the right, representing elements which are earlier in the alphabet and later in the alphabet respectively

The binary tree NULL typedef struct tree { char word[100]; struct tree *left; struct tree *right; } TREE;

Binary Tree Pros & Cons Finding an element is O(log n) Adding an element is O(log n) – O(1) if we already know where to add it. Deleting an element may be complex Programming complexity is higher than a linked list (just about)

Deleting an entire binary tree I think this code is elegant and worth looking at: void delete_tree (TREE *ptr) { if (ptr == NULL) return; delete_tree(ptr->left); delete_tree(ptr->right); free (ptr); } We can delete the whole tree with: delete_tree(root_of_tree);

Sorting again Sorting a list of numbers into order is a common problem in programming. We've already seen bubblesort in a worksheet and bogosort in this lecture. To remind you bubblesort goes: 1)Loop round the array swapping adjacent numbers if needed 2)If we made any swaps goto 1 Bubblesort is one of the simplest sorts

Quick sort Quicksort is one of the most efficient sorts 1)Pick an element of the array as the "pivot" 2)Place all elements smaller than the "pivot" on the left of the array and all elements larger on the right 3) Place the pivot in the remaining "slot" in the array 4) If there is more than one element to the left of the pivot then call 1 with the array of elements left of the pivot 5) If there is more than one element to the right of the pivot then call 1 with the array of elements right of the pivot

Quicksort In effect, we are continually dividing the array into "smaller" and "larger" parts By dividing the array into increasingly tiny sections we eventually sort it This is a good example of a recursive algorithm