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

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 conceptsNULL

head oflist

Adding an item to the middle of the list

NULLhead oflist

new itempoints at next item

movethislink

Deleting an item from the middle of the list

NULLhead oflist

move this link

delete this node

Adding to our address bookvoid 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 NULL

NULL NULL NULL

NULLNULL

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 needed2) If we made any swaps goto 1Bubblesort 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 right3) Place the pivot in the remaining "slot" in the array4) If there is more than one element to the left of the pivot then call 1 with the array of elements left of the pivot5) 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