1 C Programming Style for Engineering Computation
  2 Created by Aidan Nagorcka-Smith (aidann@student.unimelb.edu.au) 13/03/2011
  3 Definitions and imports
  4 Definitions are in UPPER_CASE
  5 Imports go before definitions
  6 Space between imports, definitions and the main function.
  7 Use definitions for any constants in your program, do not just write them in
  8 Good:
  9 #import <stdio.h>
 10 #import <stdlib.h>
 11 #define MAX_STRING_SIZE 1000
 12 #define DEBUG 0
 13 int main(int argc, char **argv) {
 14 ...
 15 Bad:
 16 /* Definitons and imports are mixed up */
 17 #import <stdlib.h>
 18 #define MAX_STING_SIZE 1000
 19 /* Definitions are given names like variables */
 20 #define debug 0
 21 #import <stdio.h>
 22 /* No spacing between imports, definitions and main function*/
 23 int main(int argc, char **argv) {
 24 ...
 25 Variables
 26 Give them useful lower_case names
 27 Initialise them to something that makes sense whereever practical.
 28 Good:
 29 int main(int argc, char **argv) {
 30 int i = 0;
 31 int num_fifties = 0;
 32 int num_twenties = 0;
 33 int num_tens = 0;
 34 ...
 35 Bad:
 36 int main(int argc, char **argv) {
 37 /* Variable not initialised - causes a bug becase we didn't remember to
 38 * set it before the loop */
 39 int i;
 40 /* Variable in all caps - we'll get confused between this and constants */
 41 int NUM_FIFTIES = 0;
 42 /* Overly abbreviated variable names make things hard. */
 43 int nt = 0
 44 while (i < 10) {
 45 ...
 46 i++;
 47 }
 48 ...
 49 Spacing:
 50 Space intelligently, vertically to group blocks of code that are doing a
 51 specific operation, or to separate variable declarations from other code.
 52 One tab of indentation within either a function or a loop.
 53 Spaces after commas.
 54 Space between ) and {
 55 No space between the ** and the argv in the definition of the main function.
 56 Lines at most 78 characters in width
 57 Closing brace goes on its own line
 58 Good:
 59 int main(int argc, char **argv) {
 60 int i = 0;
 61 for(i = 100; i >= 0; i--) {
 62 if (i > 0) {
 63 printf("%d bottles of beer, take one down and pass it around,"
 64 " %d bottles of beer.\n", i, i - 1);
 65 } else {
 66 printf("%d bottles of beer, take one down and pass it around."
 67 " We're empty.\n", i);
 68 }
 69 }
 70 return 0;
 71 }
 72 Bad:
 73 /* No space after commas
 74 * Space between the ** and argv in the main function definition
 75 * No space between the ) and { at the start of a function */
 76 int main(int argc,char ** argv){
 77 int i = 0;
 78 /* No space between variable declarations and the rest of the function.
 79 * No spaces around the boolean operators */
 80 for(i=100;i>=0;i--) {
 81 /* No indentation */
 82 if (i > 0) {
 83 /* Line too long */
 84 printf("%d bottles of beer, take one down and pass it around, %d bottles of beer.\n", i, i - 1);
 85 } else {
 86 /* Spacing for no good reason. */
 87 printf("%d bottles of beer, take one down and pass it around."
 88 " We're empty.\n", i);
 89 }
 90 }
 91 /* Closing brace not on its own line */
 92 return 0;}
 93 Braces:
 94 Opening braces go on the same line as the loop or function name
 95 Closing braces go on their own line
 96 Closing braces go at the same indentation level as the thing they are
 97 closing
 98 Good:
 99 int main(int argc, char **argv) {
100 ...
101 for(...) {
102 ...
103 }
104 return 0;
105 }
106 Bad:
107 int main(int argc, char **argv) {
108 ...
109 /* Opening brace on a different line to the for loop open */
110 for(...)
111 {
112 ...
113 /* Closing brace at a different indentation to the thing it's closing
114 */
115 }
116 /* Closing brace not on its own line. */
117 return 0;}
118 Commenting:
119 Each program should have a comment explaining what it does and who created it.
120 Any interesting code should have a comment to explain itself.
121 We should not comment obvious things - write code that documents itself
122 Good:
123 /* change.c
124 *
125 * Created by Aidan Nagorcka-Smith (aidann@student.unimelb.edu.au) 13/03/2011
126 *
127 * Print the number of each coin that would be needed to make up some change
128 * that is input by the user
129 */
130 int main(int argc, char **argv) {
131 int input_change = 0;
132 printf("Please input the value of the change (0-99 cents inclusive):\n");
133 scanf("%d", &input_change);
134 printf("\n");
135 // Valid change values are 0-99 inclusive.
136 if(input_change < 0 || input_change > 99) {
137 printf("Input not in the range 0-99.\n")
138 }
139 ...
140 Bad:
141 /* No explanation of what the program is doing */
142 int main(int argc, char **argv) {
143 /* Commenting obvious things */
144 /* Create a int variable called input_change to store the input from the
145 * user. */
146 int input_change;
147 ...
148 Code structure:
149 Fail fast - input checks should happen first, then do the computation.
150 Structure the code so that all error handling happens in an easy to read
151 location
152 Good:
153 if (input_is_bad) {
154 printf("Error: Input was not valid. Exiting.\n");
155 exit(EXIT_FAILURE);
156 }
157 /* Do computations here */
158 ...
159 Bad:
160 if (input_is_good) {
161 /* lots of computation here, pushing the else part off the screen. */
162 ...
163 } else {
164 fprintf(stderr, "Error: Input was not valid. Exiting.\n");
165 exit(EXIT_FAILURE);
166 }