7611
Comment:
|
7316
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
#All:read | #acl All:read |
Line 5: | Line 5: |
This document sets out the style for all submitted work in this course.<<FootNote(If you want to deviate from this style guide, and you think you have a ''really'' good reason why this will improve the clarity of your code, you'll need to get your tutor to approve in advance. Regardless of whether or not your tutor approves it anything you do which makes your code less clear will still incur a style mark penalty.)>> | This document sets out the mandatory style for all submitted work in first year CSE courses. |
Line 7: | Line 7: |
<<TableOfContents(2)>> | [[TableOfContents(2)]] |
Line 17: | Line 17: |
1. global vars (not used in 1917) | 1. global vars (not used in first year CSE courses) |
Line 23: | Line 23: |
1. #ifndef guard | |
Line 27: | Line 28: |
1. (extern) global vars (not used in first year comp courses) | 1. (extern) global vars (not used in first year CSE courses) |
Line 45: | Line 46: |
|| functions ||<|2(> name``Case, lowercase first letter, no spaces or _ || `buyCookie()` || || variables || `newCookie = 7;` || || anonymous variables (eg some loop counters) || single lowercase letter || `c++;` || || typedefs || Name``Case, lowercase first letter unless abstract, no spaces or _ || `typedef struct {`[[BR]]` int x;`[[BR]]` int y;`[[BR]]`} position;` || |
|| functions ||<|2(> camel``Case, lowercase first letter, no spaces or _ || `isCookie (nextItem)` || || variables || `oldCookieCount = 7;` || || anonymous variables (eg some loop counters) || single lowercase letter || `i++;` || || typedefs || camel``Case, lowercase first letter unless abstract, uppercase first letter if ADT, no spaces or _ || `typedef struct {`[[BR]]` int x;`[[BR]]` int y;`[[BR]]`} position;` || |
Line 53: | Line 54: |
* Use spaces for indents not tabs | * Use spaces for indents, not tabs |
Line 56: | Line 57: |
* MAY include one space before ( for function parameter list * use compact { } placement eg |
* MAY include one space before and/or after parentheses delimiting function parameter list * Use compact { } placement eg |
Line 59: | Line 60: |
int eatCookie (int age) { | void eatCookie (int age) { |
Line 130: | Line 131: |
* tags may be used in typedefs but not in rest of code eg in the example below would "node" not be used again in the program: | * tags may be used in typedefs but not in rest of code eg in the example below "node" would not be used again in the program: |
Line 162: | Line 163: |
* You may not use any language features or commands which have not been explicitly covered in class * so == Not used in in this course == None of the following c features may be used in your own programs unless you are explicitly instructed otherwise. We will still explain a number of these features in lectures so you can recognise them when you see them in other people's programs. |
* In assessment tasks you may not use any language features or commands which have not been explicitly covered in class * for fairness we want everyone to have the same set of tools available to solve assessment problems == C syntax not used == None of the following c features may be used in your own programs unless you are explicitly instructed otherwise. |
Line 170: | Line 172: |
* register, extern (not to be used by students, will be given by teachers as demonstration cases), short, unsigned | * register, extern (not to be used by students, will be given by teachers as demonstration cases) |
Line 172: | Line 174: |
* for (however this will be introduced in later weeks) | |
Line 182: | Line 183: |
Initially much of this document was based on "Appendix C: Cookie Programming Standards" of ''Programming Techniques using the language Cookie'', Government of South Australia, Pearson Education Australia 2005. Subsequently it has been refined and revised based on the suggestions by the 1911, 1921, and 2911 teaching staff and tutors. Thank you to all who have contributed. ---- CategoryOfficial [[:/Discuss:Comment on this page]] [[:/Admin:admin only]] |
Parts of the initial version of this document was based on "Appendix C: C Programming Standards" of ''Programming Techniques using the language C'', Government of South Australia, Pearson Education Australia 2005. Subsequently it has been expanded and revised based on the experiences of using it in our courses. It has benefited from the suggestions and comments of numerous 1911, 1921, 1917, 1927 and 2911 teaching staff and tutors. Thank you to all who have contributed. |
C Coding Style Guide
This document sets out the mandatory style for all submitted work in first year CSE courses.
C Program Layout
In a C program file items must be arranged in the following sequence:
- Header comment
- #included files
- #defines
- local struct typedefs
- local prototypes
- global vars (not used in first year CSE courses)
- main function (if present)
- local functions
In a C header (.h) file items must be arranged in the following sequence:
- Header comment
- #ifndef guard
- #included files
- #defines
- struct typedefs
- prototypes
- (extern) global vars (not used in first year CSE courses)
A header comment should include:
// WikiName (or full name for offerings without a wiki), Student Login. // Tutorial class and tutor name // Date // What this file is for (one line summary). // Possible longer explanation
Names
- all names to be meaningful
- conventions:
what
convention
example
functions
camelCase, lowercase first letter, no spaces or _
isCookie (nextItem)
variables
oldCookieCount = 7;
anonymous variables (eg some loop counters)
single lowercase letter
i++;
typedefs
camelCase, lowercase first letter unless abstract, uppercase first letter if ADT, no spaces or _
constants
UPPER_CASE, words joined with _
#define MAX_COOKIES 5
Layout
- Use spaces for indents, not tabs
- Indent 3 spaces OR 4 spaces per level, but not a mix in any file
- Describe block structures using indentation, do not rely on { } alone
- MAY include one space before and/or after parentheses delimiting function parameter list
- Use compact { } placement eg
void eatCookie (int age) { printf ("Yummy"); }
- no lines over 72 characters, (clearly) reformat expressions and comments as required to fit this limit.
- no space before commas in parameter lists, at least one space afterwards.
if, while
- always use { }, even for single statement blocks
place opening brace compactly (after condition rather than on following line), eg
while (cookies == 0) { ....; }
use compact braces around else eg
if (cookies == 0) { ....; ....; } else { ....; }
do not further indent chained else if and else statements eg
if (cookies == 0) { ....; ....; } else if (cookies < 10) { ....; } else if (cookies < 50) { ....; } else { ....; ....; }
Declarations
- Declare variables at the top of the function
Declare one per line if initialised. Only use comma separated lists of variables in a declaration when they are related instances (eg int row, col;)
- In a block of related definitions vertically align the names, types, and initialisations
- initialise variables close to where they are first used.
- all structs and enums defined with typedefs
- place prototypes for functions which are only used locally at head of file
- place typedefs for types which are only used locally at head of file
- prototypes and typedefs for functions and types which are used in multiple files are placed in a meaningfully named .h file, which is included in the file in which the function is defined and also in each file which uses the function or type
- dont #include a .h file in another .h file
Functions
- put the return type on same line as function name
- should be kept as short, and broken into sub-functions as required
- each function should have a single clearly defined purpose, this purpose should be reflected in its name.
Executable Statements
one per line, not i=0; j=0;
- don't use = as an operator
not i = j = 0
not if (x = 1)
- don't use comma operator
Function definitions
- use static for all non-interface functions in library modules
- use prototypes for all functions (even those returning int) (this permits parameter type checking)
- don't turn parameter type checking off in prototypes with (), use (void) instead
- prototypes at the top of the file
- main is to be the first function in the file, function ordering to be roughly top down
- give (sensible) variable names in prototypes
Structs
- typedefs are used to refer to structs
write struct tags (eg "node" in the example below) in lowercase
- tags may be used in typedefs but not in rest of code eg in the example below "node" would not be used again in the program:
typedef struct node Node; typedef Node *Link; struct node { Cookie cookie; Link next; };
Comments
- students have freedom in use and layout of comments, clarity is the most important criteria
blocks of comments:
style is discouraged. c99 style // at the start of each line is preferred.- tip: be wary of too many inline comments, consider replacing them with a single block header comment.
Compiler Options
- unless explicitly stated otherwise all code should be compiled with
gcc -O -Wall -Werror
Structured Programming
- all code must be structured (save exception handling using asserts). This means for example
- no multiple returns from functions
- no break
- no goto
- no return from inside a loop or if block
No shortcuts
- In assessment tasks you may not use any language features or commands which have not been explicitly covered in class
- for fairness we want everyone to have the same set of tools available to solve assessment problems
C syntax not used
- None of the following c features may be used in your own programs unless you are explicitly instructed otherwise.
ternary if operator ?:, the comma operator, = as an operator (eg if (x = 0) )
- break, continue
- switch, case
- global vars, static vars. (static function definitions WILL be used for namespace control)
- register, extern (not to be used by students, will be given by teachers as demonstration cases)
do { } while () (while () { } is used instead)
- union, enum
- tag based structs only used in the typedef of the struct, elsewhere they are referred to by the typedef name.
pointer arithmetic (e.g. pointer++), indexing from a pointer is allowed (e.g. &pointer[1])
- pointers to functions (a crude form of higher order functions, students can wait till it is done properly in an oo language)
- file IO
- const
Thanks
Parts of the initial version of this document was based on "Appendix C: C Programming Standards" of Programming Techniques using the language C, Government of South Australia, Pearson Education Australia 2005. Subsequently it has been expanded and revised based on the experiences of using it in our courses. It has benefited from the suggestions and comments of numerous 1911, 1921, 1917, 1927 and 2911 teaching staff and tutors. Thank you to all who have contributed.