All files will start with a header comment. This is just a comment that contains:

• A description of what the file is for or what the program does,
• The names and zIDs of everyone who worked on the file,
• Your tutor’s name, and
• The date that the file was made, in the form YYYY-MM-DD.

Suppose the student Julian Saknussemm was working on a program that simulated an ant farm, the header file for the antFarm.c file would look something like the following.

#includes are how we use code from other files in our .c files so that we can share functions between files. #includes always come after the header comment.

System includes, which use < and > and look like #include <stdlib.h>, are used to include header files that are installed on the operating system. These should be in alphabetical order and should come first.

Local includes, which use " and look like #include "myModule.h", are used to include our own header files. These should also be in alphabetical order and should come after system includes.

Constants are created using #define and allow us to create constant values with a name. We give these values a name near the start of our file and then we can use the name in the rest of the file. This means that if we want to change the value at any point, we only need to change it once.

If we want to use any mathematical operators in our constants, we need to surround everything with parentheses. #define can also be used to make constants with floats, chars, and strings.

Enumerated types are created using enums and allow us to create related constant values with a name and type safety. We give these related values a type name near the start of our file and names for each value of the type then we can use the values in the rest of the file. This means that if we want to change the values at any point, we only need to change it once. Enumerated types start with the first element having a value of zero, and each subsequent value being incremented by one, but this can be changed by setting the first element on the enumerated list or by setting values for each constant in the enumerated list.

Programs tend to be written in a top-down manner. This means we start at the top, at the highest level of abstraction, and progressively descend through the levels. Usually, the main function is the highest level of abstraction: the place where the program commences.

When we compile and link a program, the main function is assumed to be the place where that program’s execution starts. By convention, it takes two parameters: the count of command-line arguments, argc, and the length of the command-line argument vector, argv. These names, argc and argv, are conventions followed by most C programmers.

A general rule with file structure is that no line should be more than 72 characters wide. This means we will be able to read it in most text editors more easily.

For functions, the opening brace ({) should be on the same line as the function prototype. The closing brace (‘}’) should be on its own line and not indented.

For if, the opening brace (‘{‘) should be in the same line as if and the loop condition. The closing brace should be on its own line and should line up with the i in the matching if.

For else and else if, the else should be on the same line as the closing brace (}) before it. The opening brace ({) should be on the same line as the else, or the else if and the condition. The closing brace (}) should be on its own line and should line up with the closing brace (}) before it.

For loops, the opening brace ({) should be on the same line as while and the loop condition. The closing brace (‘}’) should be on its own line and should line up with the w in the matching while.

Variables tend to belong to the area of code that declares them, an effect known as scope. In C, it’s valid to have variables declared in the global scope. However, this is considered bad practice and should be avoided, as values in global variables may cause unintended effects in functions.

The static qualifier has a very different effect on variables to the effect it has on functions. Values in static variables persist across multiple calls to the function, which is even more insidious than global variables for introducing unintended effects.

It is possible to explicitly change the type that C considers a variable to have, using a type cast. It is very unlikely that you will need to make an explicit type cast in this course.

C allows us to jump to arbitrary locations in our program. You can see why that might be a terrible idea: there’s no guarantee that one line of code would follow another.

Unlike some other languages, C is a statement-oriented language, so an if statement doesn’t have a value. A ternary allows us to produce different values depending on a particular condition. Ternaries are a very, very easy way to produce really confusing effects, and you shouldn’t use them.

switch is an old compiler hack; it and case have subtle and confusing behaviour and you should avoid them.

The break and continue keywords can change the logical flow of control in loop statements, with the effect that the body of a loop may not proceed from top to bottom under all circumstances. It can be confusing and bizarre, and under all circumstances (that you encounter in COMP1511) you should reconsider your logic instead.

The do { ... } while (condition); construct is similar to a normal while (condition) { ... }, except the body will always run before a condition is checked. It’s very easy, as with for, to construct do...while expressions that are confusing and poorly structured, and in COMP1511 we prefer to avoid them.

Many C textbooks like for loops. Their terseness means you can cram more meaningless waffle onto a page, without actually considering the problem you’re setting out to solve.

And, as noted above, our style guide requires that a single line of code should only do one thing or have one effect; for loops demonstrate the exact opposite. Worse, in reading for loops, the order of execution is not strictly linear: the increment portion of the loop always occurs after the body of the loop, whilst the statement itself appears before it.

It’s much easier to construct a confusing and poorly structured for loop, and in COMP1511 we prefer to avoid them.

If you have a function that performs two smaller tasks in sequence, make a function for each of those smaller tasks and call them from the more abstract function. Aim for your functions to be less than 20 lines or less. If they are long, think of how you can break them up into smaller functions.

Function prototypes describe functions be telling the compiler (and anyone reading the program):

• The type of value the function returns
• The name of the function
• The type and name of any arguments to the function

When writing functions for ADTs, you may want to keep you naming consistent and the abstract type name will usually appear in the function name, usually at the end.

A space may optionally be used between the function name and argument list and the function name. The return type, function name, and start of the argument list should all be on the same line. If the argument list is too long to fit on a single line with the function name and return type, it may be split across multiple lines, with the additional lines being indented by 2 stops (8 spaces) or aligned with the first argument in the first line. Function and argument naming is discussed in the functions section of this document.

You can point at literally everything in C, even the functions you write. Function pointers are fairly dangerous, as they make it very easy to cause your program execute arbitrary code that may not be the code you expected. For the security implications alone, they’re banned.

Another, more subtle trick is the use of function pointers as a poor-man’s generic programming; that’s not ever needed in this course, so we can safely ban it.

We can create structured data using structs, which help us define a collection of related pieces of data. These allow us to contain several different values of different type in one value that can be passed around. These should always be defined after constants.

The names of struct tags must be in camel case starting with an underscore, followed by a lower-case letter. A struct should always be wrapped in a typedef so that it can be used more cleanly as a type. The type name should be the same as the struct tag, but without the underscore at the start. This type that wraps the struct is called the concrete type.

The struct pointer type should reflect the name of the struct it refers to. The typedef of a pointer to to a struct is called the abstract type.

The uppercase letter helps to distinguish between concrete and abstract types.

Files that contain a main function, should be named using camel case, starting with a lower-case letter. These should be compiled into programs of the same name, but without the .c suffix. For example, the file exampleProgram.c that contains the function main, should be compiled into the program exampleProgram (using dcc -o exampleProgram exampleProgram.c).

Later in the course, we will look at breaking programs into multiple files. We will be breaking programs into .h (header files) and multiple .c (source files).

These files will come in pairs, the header file will describe the functions and types used in the source file. To show that they are related, they will both have identical names, however the header file will end in .h and the source file will end in .c.

If the pair of files provides a set of useful functions to do related work (which we would call a module), then the names of the files will be in camel case, starting in a lower-case character. For example, we may have the module usefulModuleName, it would be split into usefulModuleName.h and usefulModuleName.c.

Later in the course, we will look at abstract data types (ADTs), which let us create our own complex data types in a way that makes them easy to use. Each ADT will have its own pair of files, much like the module, but the names will start with an upper-case letter and have the same name as the type they describe. For example, if I had files describing the ADT UsefulDataType, then they would be called UsefulDataType.h and UsefulDataType.c.

Header guards tell the compiler that we only want to use the code in a header once. This means that if we somehow #include the header multiple times, the code only gets used once. We need to do this because we aren’t allowed to define the same function or type multiple times; if we try to, the compiler will generate error messages.

Thankfully, header guards are easy. After the header comment in a .h file, you add the opening header guard and at the very end of your .h file, you add the closing header guard.

The #ifndef tells the compiler to use the code until the #endif only if the constant has not been #defined. This will only be true the first time the file is included as we then #define the constant the first time the code is used.

Pointer arithmetic is one of the stranger features of C. Pointers are, of course, numeric values, so in theory, you can manipulate them as you would any other number. In practice, though, changing pointers yourself is a bad idea, and is likely to cause serious problems.

One of the more common places we often see pointer arithmetic is string manipulation: a lazy programmer might say *string++, to get the current character in the array string, while also moving it along to the next value. This changes string, of course, meaning you lose the beginning of the string. Indirectly, the ++ is pointer arithmetic: it’s the addition of one to the value.

This is, in and of itself, fairly harmless, but ++ or +1 may not have the effect you expect if a value would take up multiple bytes. Instead, it would step along by the size, effectively emulating the behaviour of [] but being more confusing.

You should always access array elements using index notation, [].

Integer overflows are vulnerabilities where an integer can be incremented or decremented that it wraps around. This can be used to have adverse affects in a number of ways. dcc compiles your code to catch this error, so you don’t need to worry as much.

The one vulnerability that you need to look out for is buffer overflows as we cannot protect you from these so easily. A buffer overflow is where data being read into an array (usually as a string) can use up more space than the array contains and start writing into other parts of memory. If a user can control this, then they may be able to run code from within your program.

The best things to keep in mind when dealing with arrays are:

• Am I sure that data can’t be written past the end of the array?
• Am I sure that the last byte in the array will always be a terminating character ('\0') or unused?
• Can I ensure that there is a limit on how many bytes of characters are read.

The printf function uses a string as its first argument to tell it how to format the remaining variables passed into the function. If a user can control what string is used for a printf statement, they not only have the ability to read all of the data in memory, but due to a quirk in the way printf can be used, they can also run their own code from within your program. Basically, you should never have a printf statement with a variable as the first argument.

The compiler will warn you if your code contains printf vulnerabilities.