If you do not have much coding experience, it is strongly recommended you only use C language features that have been described in lectures. You will find it much easier to follow the same collective path as the rest of the class.
If you have significant programming experience you are in general free to use language features you have learned outside this course, unless it is explicitly forbidden below. But please bear in mind you may not be able to get assistance from tutors, or in the course forum with your code.
All program should have a header comment.
For small lab exercises the header comment should contain at least:
- The names of the author(s) - include your UNSW zID with any code you submit at UNSW.
- The date it was written.
- A description of what the program does.
For larger programs such as assignments, also include:
- An overview of how the program works, including any bugs or limitations.
- Any other information that might help a reader understand the code.
- References to resources used in constructing the code.
It is not necessary to include licensing information, but it is commonly present in header comments of code outside uni.
All program should have a header comment.
For small lab exercises the header comment should contain at least:
- The names of the author(s) - include your UNSW zID with any code you submit at UNSW.
- The date it was written.
- A description of what the program does.
For larger programs such as assignments, also include:
- An overview of how the program works, including any bugs or limitations.
- Any other information that might help a reader understand the code.
- References to resources used in constructing the code.
It is not necessary to include licensing information, but it is commonly present in header comments of code outside uni.
//
// COMP1511 Lab 10 Exercise - Turing's test
//
// Pretend to be a human in text-based conversation.
// https://en.wikipedia.org/wiki/Turing_test
//
// Authors:
// Grace Hopper (z1234567@unsw.edu.au)
// Ada Lovelace (z5000000@unsw.edu.au)
//
//
//
// Written: 19/03/2019
//
#include <stdio.h>
#include <string.h>
#include <math.h>
#define MEANING_OF_LIFE 42
// function prototypes would go here
int main(void) {
printf("Hello!\n");
return 0;
}
// function definitions would go here
Functions, loops, and ifs should always use braces and should use compact braces.
Functions, loops, and ifs should always use braces and should use compact braces.
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.
Functions, loops, and ifs should always use braces and should use compact braces.
int someFunction(int a, int b) {
if (a > b) {
// do something
} else if (b < a) {
// do something
} else {
// do something
}
int i = 0;
while (i < 0) {
// do something
i++;
}
}
Functions, loops, and ifs should always use braces and should use compact braces.
// BAD - the code between the {} should be indented if (i % 2 == 0) { printf("even"); } else { printf("odd"); } // BAD - put newlines after { and after } while (i < 0) { i++; } // BAD - always use braces on ifs and whiles while (i < 0) i++; // BAD - closing braces don't line up if (a > b) { // do something } else if (b < a) { // do something } else { // do something }
Between any pair of braces, the indentation level should increase by 4 spaces. Spaces should be used for all indentation.
Use a space after keywords such as:
if, while, for, returnUse a space on each side of binary operators such as
= + - < > * / % <= >= == !=Do not use space after prefix unary operators such as
& * !Do not use space before postfix unary operators such as
++ --Do not use space on each side of member access operators such as. ->
Use a space after keywords such as:
if, while, for, returnUse a space on each side of binary operators such as
= + - < > * / % <= >= == !=Do not use space after prefix unary operators such as
& * !Do not use space before postfix unary operators such as
++ --Do not use space on each side of member access operators such as. ->
// This is correct:
if (a + b > c) {
i++;
curr = curr->next;
}
// This is *not* correct:
if(a+b>c) {
i ++;
curr = curr -> next;
}
Only one executable statement should be used per line of code.
Only one executable statement should be used per line of code.
Don't put multiple statements on a single line - it makes code very hard to read.
Keep lines under 80 characters.
Keep lines under 80 characters.
Break long lines up to keep them under 80 characters, unless keeping it as a longer line is significantly more readable.
Keep lines under 80 characters.
// This is WAY too long:
if (something && somethingElse && somethingElseAgain && anotherThing && evenMoreThings && somethingElseEntirely && thereAreTooManyConditions && thisLineIsTooLong) {
// This is better (but consider using a function instead):
if (something && somethingElse && somethingElseAgain && anotherThing &&
evenMoreThings && somethingElseEntirely && thereAreTooManyConditions &&
thisLineIsTooLong) {
// This is best:
if (thoseThingsAreTrue()) {
Use
#defineto give constants names.
#definesmust be written inALL_CAPS_WITH_UNDERSCORES.
Use
#defineto give constants names.
#definesmust be written inALL_CAPS_WITH_UNDERSCORES.
Unexplained numbers,often called magic numbers, appearing in code make it hard to understand.
If a number appears multiple times in the code, bugs are created when the code changed but not all occurrences of the number are changed.
A similar problem is that a number may appear in the code for multiple reasons, e.g. a commonly used number like 10, and if the code needs to be changed it can be hard to determine which occurrences of the number should be changed.
enum is also used be programmers to give constants names in C.
Use
#defineto give constants names.
#definesmust be written inALL_CAPS_WITH_UNDERSCORES.
#define DAYS_OF_WEEK 7
// ....
int array[DAYS_OF_WEEK];
int i = 0;
while (i < DAYS_OF_WEEK) {
a[i] = i;
i++;
}
Use
#defineto give constants names.
#definesmust be written inALL_CAPS_WITH_UNDERSCORES.
// BAD - the constant 7 should be given a name int array[7]; int i = 0; while (i < 7) { a[i] = i; i++; }
Descriptive variable names should always be used where possible.
Short variable names such as
xoriare acceptable if there is no appropriate long descriptive name. This is often the case for variables used as loop counters.Variable names must begin with a lower case letter.
Multi-word variable names be in either snake_case or camelCase. Use only one of these approaches in your program.
#definenames must be inALL_CAPS_WITH_UNDERSCORES.
Variables can be declared when they are first assigned a value, as part of assigning the value.
Variables can be declared when they are first assigned a value, as part of assigning the value.
// This is fine:
int i = 0;
// Probably avoid this:
int i;
[insert a lot of other code here]
i = 0;
Use only the types
intanddoublefor numeric variables.You should not need to use other types such as
shortandfloatin this course.You will need to use the type
charfor arrays, but do not use the typecharfor simple variables.
Use only the types
intanddoublefor numeric variables.You should not need to use other types such as
shortandfloatin this course.You will need to use the type
charfor arrays, but do not use the typecharfor simple variables.
// DO NOT do this
short age = 18;
float height = 1.65;
char c = 'A';
// Instead do this:
int age = 18;
double height = 1.65;
int c = 'A';
// common C programming bug - getchar returns an int
char c = getchar();
It is recommended variables controlling
whileloops be declared before the loop and used only to control that loop.It is recommended variables controlling
forloops be declared as part of the for loop
It is recommended variables controlling
whileloops be declared before the loop and used only to control that loop.It is recommended variables controlling
forloops be declared as part of the for loop
int i = 0;
while (i < MAXIMUM) {
// do something
i++;
}
for (int i = 0; i < MAXIMUM; i++) {
// do something
}
Global variables should not be used. Static variables should not be used.
Global variables should not be used. Static variables should not be used.
Global variables are variables that are declared outside of a function.
Global variables make code hard to read, maintain and parallelize.
There are important uses for global variables but not in this course.
There is likely to be a major style deduction if you use global variables.
The only acceptable use likely in this course would be a global variable to control debug output.
All the above also applies to variables inside functions which have
the static qualifier.
The values in static variables persist across multiple calls to the
function creating similar problems.
There is likely to be a major style deduction if you use static variables.
Variable-length arrays should not be used in this course.
Variable-length arrays should not be used in this course.
Variable-length arrays are arrays whose size is not known when the program compiles.
Arrays should only be declared with a constant size, such as with a literal integer
e.g. int array[12], or with a constant, e.g. int array[MAX_LENGTH].
Arrays should not be declared with a size using a variable, such as int array[x].
Many C implementations handle poorly local variables consuming more than a small amount of memory, often terminating with a cryptic message if the storage used for local variables exceeds a few megabytes.
This applies both to arrays with size fixed at compile-time and variable-length arrays.
For this reason programmers often use malloc for larger arrays (10000+ elements). malloc gives the programmer complete control over storage lifetime, but as a consequence introduces other classes of bugs.
Unless a task specifies otherwise, you are only permitted to call functions from the standard C library.
The standard C library includes functions declared in
stdio.h,stdlib.h,string.h,math.handctype.h.You are not permitted to use functions such as
read,writeandopendefined inunistd.h. They are not part of the standard C library.You are not permitted to use the
-loption to dcc to include other libraries.Note: the
math.hlibrary is part of the standard C library and are you are allowed to use it. dcc includes it by default, but gcc and clang require you to compile with a-lmoption to use the maths library.
Unless a task specifies otherwise, you are not permitted to run other programs from your C program, using the function
systemor otherwise.
Your code should not generate any warnings or errors when compiled with dcc.
You should assume warnings from dcc are errors that need to be fixed.
Your code should not perform any operation which results in undefined behaviour or a runtime error (when given any input that is permitted for the exercise).
For example, you must ensure your code does not access uninitialized variables, overflow numeric variables, access non-existent illegal array elements or dereference NULL pointers.
All of these will heavily penalized in marking.
Your code should not perform any operation which results in undefined behaviour or a runtime error (when given any input that is permitted for the exercise).
For example, you must ensure your code does not access uninitialized variables, overflow numeric variables, access non-existent illegal array elements or dereference NULL pointers.
All of these will heavily penalized in marking.
Novice programmers need to be very careful that their code is not invalid.
For example, they need to carefully consider whether an expression used to index an array will always result in a valid array index.
Invalid C is a frequent source of serious security exploits - for example attackers often exploit invalid array indices and integer overflows.
Do not cut-and-paste code. The same code should not appear twice in your program. Avoid repeating code by defining a function and calling it twice (or more).
Do not cut-and-paste code. The same code should not appear twice in your program. Avoid repeating code by defining a function and calling it twice (or more).
Repeated code makes your program hard to understand and hard to change.
Functions should have one clearly defined purpose and should be short.
"Functions should do one thing, and one thing only."
Functions should have one clearly defined purpose and should be short.
"Functions should do one thing, and one thing only."
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 must be used for all functions (except
main) and must come before all functions, appearing in the same order as the function implementations.Function signatures must have the return type, function name, and state the argument list.
Function prototypes must be used for all functions (except
main) and must come before all functions, appearing in the same order as the function implementations.Function signatures must have the return type, function name, and state the argument list.
Function prototypes describe functions be telling the compiler (and anyone reading the program):
Every function must have a comment placed before the function implementation describing the purpose of the function and any side-effects the function has.
Every function must have a comment placed before the function implementation describing the purpose of the function and any side-effects the function has.
// return pointer to last node in list
// NULL is returned if list is empty
struct node *last(struct node *head) {
Function names should be descriptive, typically containing multiple words. Function names containing multiple words should be in either snake_case or camelCase. Do not use both approaches in the one program.
Function names should be descriptive, typically containing multiple words. Function names containing multiple words should be in either snake_case or camelCase. Do not use both approaches in the one program.
When writing functions for ADTs, you may want to keep your naming consistent and the abstract type name will usually appear in the function name, usually at the end.
Argument names in a function prototype should match the names used in the function implementation and should always be used in the prototype.
Long function argument lists may be broken over multiple lines.
Functions that do not take any arguments should use
(void)instead of an empty argument list.
Argument names in a function prototype should match the names used in the function implementation and should always be used in the prototype.
Long function argument lists may be broken over multiple lines.
Functions that do not take any arguments should use
(void)instead of an empty argument list.
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.
Argument names in a function prototype should match the names used in the function implementation and should always be used in the prototype.
Long function argument lists may be broken over multiple lines.
Functions that do not take any arguments should use
(void)instead of an empty argument list.
// A short function
int aFunctionWithNoArguments(void);
// A short function
int aSimpleFunction(int argumentA, char *argumentB);
// A function with a lot of arguments
int aLongFunction(int argumentA, int argumentB, int argumentC, int argumentD,
int argumentE, int argumentF);
// Another function with a lot of arguments
int anotherLongFunction(int argumentA, int argumentB, int argumentC,
int argumentD, int argumentE, int argumentF);
// Another function with a lot of arguments.
// Note that the closing ');' is on a line by itself to make it clearer where
// the prototype ends.
int anotherLongFunction(
int argumentA, int argumentB, int argumentC,
int argumentD, int argumentE, int argumentF
);
Minimise the number of return statements in your functions.
Have multiple multiple returns only if this makes your function less complex or more readable.
For example, it is acceptable to have an early
returnstatement(s) to handle error conditions or special cases, as well as another return statement for the computation of the function's main result.
Minimize use of
breakstatements.
Minimize use of
breakstatements.
Novice programmers often over-use break statements.
producing confusing and difficult to debug code.
Use break only when you are sure it makes your
code simpler and more readable.
Avoid using the
continuestatement.
Avoid using the
continuestatement.
Novice programmers often misuse and over-use continue statements,
producing confusing and difficult to debug code.
It is best not to use continue are until you are a more experienced
programmer - and then use it carefully ensuring it makes your code more readable.
Do not use
#definestatements with parameters (usually called macros).Define a function instead.
Do not use
#definestatements with parameters (usually called macros).Define a function instead.
Macros introduce a nasty class of bugs due to their implementation as textual pre-processing.
Macros were primarily used for efficiency in the past. This is no longer needed.
Modern C compilers will produce the same code for functions as for macros, without the risk of nasty bugs.
There will be a style deduction if you use macros.
Avoid pointer Arithmetic.
Use array indices instead.
Avoid pointer Arithmetic.
Use array indices instead.
Experienced programmers use pointer arithmetic to produce succinct idiomatic code.
Novice programmers confuse themselves by trying to use pointer arithmetic. Any code using pointer arithmetic can also be written using array indices. Use array indices until you are an experienced programmer.
Avoid type casts, except converting between numeric types such as
inttodouble.
Avoid type casts, except converting between numeric types such as
inttodouble.
Safe use of type casts, other than between numeric types, involves a deep knowledge of C semantics.
A need for other uses for type casts should not arise in this course, and other uses for type casts should be avoided.
An exception would be implementing your own collections data types, for an advanced exercise or the challenge part of an assignment.
Avoid type casts, except converting between numeric types such as
inttodouble.
int x = 42;
int y = 11;
double f;
f = x/((double)y); // convert y to a double
Avoid the
switchstatement.Use
if...else if...elseinstead.
Avoid the
switchstatement.Use
if...else if...elseinstead.
The C switch statement can have subtle and confusing behaviour.
While there are some circumstances, e.g. writing emulators where its use is desirable, leave its use until you are a more experienced programmer.
Use if...else if...else instead.
Do not use
goto.
Do not use
goto.
Most programmers completely avoid use of the goto statement because
it can produce incomprehensible code.
Introductory programming courses always ban use of goto to help
beginner programmers learn better coding techniques.
There are very limited circumstances, e.g. writing device drivers or emulators, where goto's use is appropriate
These circumstances will not arise in this course.
There will be a major style deduction if you use goto.
Avoid using the comma operator to combine multiple expressions.
Avoid using the comma operator to combine multiple expressions.
Novice programmers attempting to use the comma operator typically construct unreadable code and confuse themselves.
Avoid using the ternary if:
(condition) ? true_expression : false_expressionshould not be used.
Avoid using the ternary if:
(condition) ? true_expression : false_expressionshould not be used.
Unlike some other languages,
C is a statement-oriented language;
this means, for example, an if statement
doesn't have an inherent value and can't be used inside an expression.
C does have an operator similar to the if statement,the ternary if, which can be used in expressions.
Novice programmers attempting to use the ternary if typically construct unreadable code and confuse themselves.
Most experienced programmers either avoid the ternary if entirely,
or use it very limited circumstances which should not arise in this course.
do...while
Avoid using
do {} while (condition);usewhile (condition) {}instead.
do...while
Avoid using
do {} while (condition);usewhile (condition) {}instead.
The do { ... } while (condition); construct
is similar to a normal while (condition) { ... },
except the body will always run
before a condition is checked.
Novice programmers often confuse themselves and construct hard to debug code using do...while loops.
Many experienced programmers avoid do...while entirely, but they are commonly used in some
contexts such as kernel programming by experienced programmers.
union
Do not use
unions usestructs instead.
union
Do not use
unions usestructs instead.
Unions allow a polymorphic datatype to occupy less space than if a struct was used.
No need for this should arise in this course.
Union introduce a nasty class of bugs which are hard to debug and best avoided by novice programmers.
Unions are also sometimes useful for embedded programming and for building language implementations.