C Programming Standards PDF

Preview

Summary

Download C Programming Standards PDF

Description

CS 158/159 C Programming Standards Alan Bunning Department of Computer Science Purdue University

1. Introduction The requirement of having good programming standards is universally practiced among corporate professionals. Most companies have extensive documentation on their programming standards in order to facilitate the transfer of previously developed code from one employee to another without having to understand the idiosyncrasies or each individual’s programming style. For this course, programming standards are maintained for the following three reasons: 1. Programming standards will help ensure that your code is as easy to understand for your lab instructor to grade as possible. With hundreds of programs to grade each week, these standards provide the lab instructors with a consistent way to evaluate every program in a uniform manner across sections. They also help the lab instructors to quickly understand your code when you are seeking their assistance. 2. Programming standards will help you avoid introducing errors in your programs. There are a number of constructs that are allowable according to the C syntax which are not conducive to good programing practices, and whose usage is likewise prohibited among corporate professionals. Such constructs are purposely avoided because they are difficult to debug, horrendous to maintain, and often produce unpredictable results. 3. Programming standards will help you develop good programming practices and aid you in any future programming endeavors. There are certain programming practices which have been universally accepted over time among corporate professionals because they produce better results. These standards will help you resist falling into bad programming habits which you would have to later break. After working with different lab partners through the semester, many of you will be thankful for having these practices in place to guide you. These standards are not merely suggestions, they are required for the course and failure to fully comply with these standards will result in a reduction of points. You will need to continue to refer to these standards as you write programs throughout the semester. Various examples from the textbook or notes may not abide by all of these programming standards, but the programs you submit for grading are still required to abide by these standards.

2. Comments Program Header Comments ●

Every program must be preceded with a header comment which adheres to the following format: /*************************************************************************** * Assignment: either Lab # or Homework # * Lab Section: the day, time, and location of your lab meeting * Description: verbose description of what the program does * Programmers: fullname1 [email protected] * fullname2 [email protected] * fullname3 [email protected] ***************************************************************************/

The full name and the official Purdue career account e-mail address must be included for each participating member. If an e-mail address is incorrect, it will result in no credit being assigned to those individuals (including the submitter). ● For homeworks, only one e-mail address of the individual submitting the homework should be listed. ● For labs, do not include the e-mail address of any individual that did not participate in the programming process. ● A verbose program description is necessary in order to help your grader understand your code and determine the algorithm you were attempting to implement. ●

User-Defined Function Header Comments ●

Every user-define function (not including main) must be preceded with a header comment which adheres to the following format: /*************************************************************************** * Function: function name * Description: brief description of what the function does * Parameters: variable1 name, data type, and description * variable2 name, data type, and description * Return: data type and description ***************************************************************************/

Variable Declaration Comments ●

Each variable declaration must be on a separate line with a comment that explains what its purpose is. This includes any variables that are declared in functions. For example, int length; float rate; char answer;

// length of the rectangle // interest rate of the loan // receives user answer of ‘y’ or ‘n’

Program Statements Comments ●

It is expected that various sections of code throughout the program be commented to inform others (especially the grader) regarding the logic that you are attempting to implement. Do not place a comment next to every line of code in your program.

Line comments // should be separated from the code on the same line by at least 1 space, making it easier to see where the code ends and the comment begins. ● Block comments /* */ should be used to explain sections of code that require more complicated explanations. Note that block comments cannot be nested in the C language.

●

3. Formatting White-Space One space should be placed between all operators and operands (except for unary operators). For example: y = 5 * (x / z) – g++; ● Use blank lines between sections of code to help show logical groupings of statements. Do not add unnecessary blanks line or double-space all lines of code. ● All code inside the body of a programming construct must indented by two spaces.

●

Brackets ●

Any block of statements in a programming construct that exceeds more than 1 line must be enclosed in brackets. Brackets are indented at the same level as the programming construct and the block of statements are indented by 2 spaces. For example,

●

if (expression) { statements } else { statements }

switch (expression) { case value1: statements break; default: statements }

type function (parameters) { statements }

while (expression) { statements }

do { statements } while (expression);

for (expr1; expr2; expr3) { statements }

Other alternate forms of bracket usage are not allowed such as if (expression) { statements }

●

if (expression) { statements }

Nested structures must be indented an additional 2 spaces for each level. For example, if (expression) { while (expression) { statements } }

●

A single line in the body of a programming construct does not have to be enclosed in brackets. For example, if (expression) statement; else statement;

while (expression) statement;

4. Identifiers All variable, constant, and function identifiers should consist of mnemonic names which have a meaning that suggests the purpose of the identifier in the program. ● All variable and function identifiers should normally be in all lower-case letters, except for capital letters which optionally may be used to delimit multiple words (called camelCasing). For example: numItems, minScoreRequired, etc. The underscore should not be used for these identifiers. ● The use of single letter identifiers should generally not be used except for counter variables which serve no other purpose than to count from a starting point to an ending point. An exception might also be made in cases where the entity is normally represented by a single letter; thus using x, y, and z for 3D coordinates would be acceptable. ● The use of memory constants using the const statement is not allowed. Symbolic/defined constants using #define pre-processor directions should be used instead. ●

Symbolic/Defined Constants Any #define pre-processor directives (symbolic/defined constants) must go at the top of your program, just below the program header and any #include directives. ● The names of symbolic/defined constants must be all uppercase letters and an underscore may be used to separate different words. For example: #define MAX_SIZE 15 ● The use of literal constants should be minimized and any repeated use of a constant should be initialized as a symbolic/defined constant.

●

Variable Declarations Variable declarations must always be separated from the executable statements and must always be declared at the top of the function they reside in (including main). Variables may not be declared later down in the body of the code. ● All variable and symbolic/defined constant declarations must be done one per one line followed by a descriptive comment. ● Global variables (which are declared before the main function) are not permitted. If variables need to be shared with other functions, you will need to pass them as parameters. ● Do not reuse any identifier that is inside two objects that have overlapping scope. Always pick separate names to avoid confusion.

●

5. Program Constructs Standard Libraries Any #include pre-processor directives must go at the top of your program, just below the program header comment. ● You are only permitted to use the standard C libraries functions mentioned in the book or introduced in class up to the current chapter.

●

Selection ●

Do not use a null statement as a clause in an if statement, but instead rewrite the condition of the if statement so that a null statement is not needed.

Repetition The use of the comma operator in the expression portion of any loop is not allowed. The use of break, continue, and goto statements are not allowed for they violate the classic rules of structured programming, where each construct only has one entry and one exit point. The break statement, however, may be used in the switch statement. ● Use for loops only with counter-controlled processes. You must make use of all three expressions with every for loop. Do not leave expressions empty or place meaningless statements in any of the expressions. ● The use of recursion is discouraged and should never be used for this course. ● ●

Functions ●

● ● ● ● ●

After functions are introduced, the only statements allowed in the main program are the declaration of variables needed to be passed between function, the functions called by main and a minimum amount of control code (loops and selection) to direct the central processing. Each function should be functionally cohesive such that it completes only a single fundamental task. Do not combine several unrelated tasks in a function. All function declarations should have a global scope. Do not declare a function inside of another function. All function declarations must explicitly include the data types for each parameter. Every function should have exactly one return statement, even if it is void, and it must be the last statement in the function. You may not use the return statement to prematurely exit a programming construct. Passing parameters by address should be minimized and only used when more than one value needs to be revised and the altered values need to be retained in the calling function after the called function terminates.

File Input/Output If a file is opened with the fopen statement, the result must checked to sure that the file exists before proceeding in the program. ● Every file that is opened with the fopen statement must later be explicitly closed with the fclose statement. ●

Arrays All arrays must be of fixed length and a symbolic/defined constant must always be used to indicate the size of the array when it is declared. The symbolic/defined constant should also be used whenever possible to refer to the bounds of the array. ● The use of variable-length arrays is not acceptable and thus a variable should never be used to define the size of an array. ●

6. Implementation Compilation Errors and Warnings All programs must be compiled and submitted using the compiler specified for this course using the gcc compiler on guru.itap.purdue.edu as set up during the first week of the semester. ● All compiler warning messages should be eliminated prior to the submission of your final effort. The presence of compiler warnings will result in a reduction of points. ● Any assignment submitted that does not compile because of a syntax error will not receive any points. It does not matter how trivial the syntax error is, you are responsible for ensuring that your work is correct prior to submission. ●

Advanced Implementations ●

You may not exceed the programing concepts mentioned in the book or introduced in class up to the current chapter. If you are not sure if a particular programming construct is allowed, you must receive permission from the course instructors.

●

The presence of advanced programming methods that have not been covered yet is viewed as suspicious activity, for if it goes beyond the ability of what most students are capable of doing, it is suspected that the code may have been submitted or copied by someone else.

Efficient Design ● ● ● ● ●

It is expected that every program will be designed to be relatively efficient in its approach. A program that is uses unnecessary statements or is needlessly slow because of poor design will receive a reduction in points. Do not waste CPU resources by using nested loops if a task can be implemented in one loop (or none). Do not waste memory by using arrays if they are not necessary or multiple arrays if one will suffice. Avoid duplication of the same code within a program and consolidate repetitive patterns of code into functions. The program should be as succinct and logical as possible. Illogical code that is obfuscated or hard to follow may result in a reduction in points.

Program Example /*************************************************************************** * Assignment: Lab 13 * Lab Section: Monday 11:30 SC 189 * Description: Get a number of weeks from the user and displays the total * number of days in that number of weeks. * Programmers: Joe Blow [email protected] * John Smith [email protected] * Jane Doe [email protected] ***************************************************************************/ #include #define DAYS_PER_WEEK 7 // number of days in a week // function declarations int getWeeks(); // returns number of weeks specified by the user int main() { int totalDays;

// total number of days

// calculate number of days in number of weeks specified by user totalDays = getWeeks() * DAYS_PER_WEEK; // print out the total number of days printf("The total number of days is: %d\n", totalDays); } /*************************************************************************** * Function: getWeeks * Description: Get the desired number of weeks from the user and return that * value. * Parameters: none * Return: integer - number of weeks ***************************************************************************/ int getWeeks() { int weeks; // value to be entered by the user // get the number of weeks from the user printf("Enter the number of weeks: "); scanf("%d", &weeks); return weeks; }

// return the value...