Você está na página 1de 4

CSC 190 H1S

Programming Style Conventions

Winter 2011

Introduction
You should take the style conventions you are required to use very seriously, because your instructor and your marker(s)and, eventually, your employerwill surely do so. This document is adapted from http://cs.stmarys.ca/~porter/csc/341/2008/.

The Big Three of Programming Style


Name things well, using the specied style conventions. Be consistent. Format continually, and re-format whenever necessary. The importance of choosing a good name for each programmer-named entity, thereafter spelling and capitalizing that name appropriately and consistently, and continuing to position these names properly within well-formatted code, cannot be overemphasized. Remember that the main consumers of your code will be other humans! Your top priority should always be to make your code as easy to read and understand as possible, and this is what these conventions are all about.

Naming
Names must be meaningful within their given context whenever possible, which is most of the time. Two exceptions to this rule are: The use of single-letter loop control variables such as i in those situations where no particular meaning attaches to the variable. Use of a generic variable name such as x for reading in values (real numbers, say) to which no particular meaning applies. A good rule-of-thumb to use is that a names length (and descriptiveness) should be roughly proportional to its scope (the amount of code that uses the name). For example, a short functions parameters can have short names, but a preprocessor constant used in multiple functions should have a longer name. Variables and value-returning functions are generally noun-like, as in: length number_of_students average_score() Boolean variables and functions, however, are usually adjective-like, as in: valid is_finished() The name of every void function must begin with a verb, as in: get_input_from_user() display_counter() Occasionally value-returning functions may also begin with a verb. Engineering Science, University of Toronto Page 1 of 4

CSC 190 H1S

Programming Style Conventions

Winter 2011

Capitalization
Names must always be capitalized consistently, according to the following conventions for each category of name. Constants use all uppercase letters, with the words in multi-word names separated by underscores, as in: #define SIZE 100 const double TAX_RATE = 0.15; Variables use pothole notation, which means that names start with a lowercase letter, and mutiple words in the name, if any, are separated with an underscore, as in: double cost; int number_of_guesses; Macro denitions used in header les to avoid multiple inclusion are a special case, and their capitalization is illustrated by this example for a le menu.h (containing the specication of functions related to manipulating menus): #ifndef MENU_H #define MENU_H ... #endif//MENU_H Functions start with a lowercase letter: double average(); void display_menu(); User-dened type names start with a lowercase letter, end with _t, and should be nouns that are singular, as in: menu_t text_item_collection_t random_generator_t

Indentation and alignment


Use an indentation level of 4 spaces, and always use actual spaces, never the TAB character. Indent and align each of the following: Statements in the body of a function (with respect to the corresponding function header). Statements in the body of a loop (with respect to the loop keyword(s)). Statements in the body of an if and, if the else is present, in the body of the elsethe statements in the body of an if should always align with those in the body of the corresponding else, and the if and else must themselves align, unless the entire if...else construct is a short one on a single line. Field denitions in the denition of a struct. Each level of nesting requires another level of indentation. Align enclosing braces vertically with each other (or place the opening brace at the end of the line preceding the block), except in very rare cases. [A short array initialization comes to mind as an exception.] Situations where braces must be aligned vertically include: Engineering Science, University of Toronto Page 2 of 4

CSC 190 H1S

Programming Style Conventions

Winter 2011

The braces enclosing a function body with the function header. The braces enclosing a loop body in a while, do...while or for loop. The braces enclosing the body of an if, else or switch with the corresponding if, else or switch. The braces enclosing the body of a struct with the keyword struct. Align comments with the thing commentedhorizontally if the comment ts on the same line, vertically if the comment takes up multiple lines. If a statement extends over more than one line, indent and align the second and any subsequent lines for readability (which may sometimes mean ignoring the 4-space-indentation rule for those lines).

Whitespace
Use vertical spacing to enhance readability. For example, use one or more blank lines to separate logically distinct parts of a program. In general, dont be afraid to use more vertical whitespace, rather than less. Use horizontal spacing to enhance readability. For example, you should place a blank space on each side of an operator such as || or +, and leave a blank space after every comma in a function call. This rule is to be relaxed in long complex expressions, such as nested function calls. Use a space between the selection or looping keyword and the following left parenthesis. if (condition) ... while (condition) ... for (...) Omit spaces around the left and right parenthesis in a parameter list. void increment_count(int count); important_value = generate_important_value(2, 3, 4);

Comments
When commenting your code, you should strive to be informative without being excessive. Your goal is to have readable code, and too many comments can often be nearly as bad as, and sometimes worse than, too few. In particular, comments should always describe the purpose or meaning of pieces of code, and not simply repeat what the code is doing. At the beginning of a le, always have a comment containing the name of the le, and a comment containing the purpose of the code in that le. These two comments can often be one line each. For each function, include the following information in the given order (and note that we require the information to be present in specication (header) les, but we allow it to be omitted in implementation les, since the appearance of the same information in two dierent locations generally leads to a maintenance nightmare): One or more comment statements describing in summary form (or more detailed form if necessary) what the function does. The return value of the function, including values that indicate error conditions. A list of the functions parameters in the same order as they appear in the parameter list, with a description of each. The functions pre-conditions and post-conditions. Engineering Science, University of Toronto Page 3 of 4

CSC 190 H1S

Programming Style Conventions

Winter 2011

Program Structure
When your entire program is contained in a single source le, that le should have the following code sections in the given order: Comments indicating the name of the le, purpose of the code in that le, and anything else that may be required in these initial comments for the particular occasion. The necessary #includes for the required header les. Denitions for any global constants and global data types, and declarations of any explicitly permitted global variables. Prototypes for any required functions, grouped in some intelligent way that will depend on the nature of the program. The main function. Denitions for each of the functions whose prototypes appeared before main, and in the same order as the corresponding prototypes. When you have a multi-le program, each le should follow the above guidelines, except of course that only one le will have a main function in it, and function prototypes are generally in a dierent le from the corresponding function denitions. The contents of any one le should form a logical grouping of some kind within the context of the overall program.

Maximum Length of Source Code Lines


No line in any code submitted should ever be more than 80 characters long.

No TAB Characters in Source Code


Your source code must not contain any TAB characters.

Be Consistent!
Where there is some room for choice, pick one style and apply it everywhere. Even if youre not sure your choice is the best one, your code will be much more readable if its style is consistentor to put it another way, code that mixes various styles is much harder to read.

Miscellaneous
Put each program statement on a separate line, unless you can make a very good argument to explain why you didnt. One such argument might be that you used a one-line-but-multi-statement C idiom of some kind. Use named constants (#define) whenever appropriate. Always protect header les (and other les to be included) against multiple inclusion, using the #ifndef ... #endif trick.

Engineering Science, University of Toronto

Page 4 of 4

Você também pode gostar