Welcome to Scribd, the world's digital library. Read, publish, and share books and documents. See more
Download
Standard view
Full view
of .
Look up keyword
Like this
2Activity
0 of .
Results for:
No results containing your search query
P. 1
Coding Guidelines

Coding Guidelines

Ratings: (0)|Views: 25|Likes:
Published by api-3715867

More info:

Published by: api-3715867 on Oct 14, 2008
Copyright:Attribution Non-commercial

Availability:

Read on Scribd mobile: iPhone, iPad and Android.
download as DOC, PDF, TXT or read online from Scribd
See more
See less

03/18/2014

pdf

text

original

Coding Guidelines
Table of Contents
Introduction
Guidelines
Identifiers

Abbreviation is your enemy.
When an identifier\u2019s name gets to be longer than 30 characters, consider renaming it.
Underscores_are_your_friends.
Avoid using two underscores in a row.
Capitalization makes identifiers even easier to read.
Avoid using all capital letters for names of constants.
Avoid including the type of the variable in its name.
Name a variable based on its usage.
If a variable has the same name as another variable in a larger scope, consider renaming the smaller scope variable.
Avoid having the only difference between two identifiers be upper versus lower case.

Whitespace

Place a space after an identifier if it is followed by an open bracket.
Do not place a space after an open bracket if it is followed by an identifier.
Do not place a space after an identifier if it is followed by an close bracket.
Do not place a space between two of the same brackets.
Place a space between a close bracket and an open bracket of the same type.
Do not place a space between an open bracket and a close bracket of the same type.
Place a space after a comma.
Place a space on both sides of a mathematical or comparison operator (including '?' and ':').
Place a space after an identifier if it is followed by an asterisk ('*').
Do not place a space after an asterisk ('*') if it is followed by an identifier.
Do not place a space after an identifier if it is followed by an ampersand ('&').
Place a space after an ampersand ('&') if it is followed by an identifier.
Never use hard tabs in your source files (have your editor insert spaces instead of tabs).
Place a space after a semicolon (';') unless it is followed by another semicolon or at the end of a line.
Do not place a space on either side of a scope resolution operator ("::").
Place a space between the word "operator" and the operator itself when writing an operator overload function.
Place a blank line between function definitions.
Do not place a space after an exclamation point ('!').

Code Formatting

Place a curly bracket on its own line and line it up vertically with the matching curly bracket.
Always indent code appearing after an open curly bracket.
If a line is wider than one screen width (this may vary depending on the editor you use), consider finding a good place to split
the statement and putting it on two lines.
When using a constant in a comparison expression, always place the constant on the left side of the comparison operator.
When the difference is unimportant, always use ++prepending instead of postpending++ increment/decrement.
For a function with a large number of arguments, it is okay to declare the function with one variable on its own line.
Always place a curly bracket after an if statement, even if there is only one statement being controlled by the condition.
Always line up the 'else' keyword vertically with its matching 'if' keyword.
If an expression is long enough to require multiple lines, start the next line with an operator as opposed to leaving a 'dangling'
operator at the end of the previous line.
Instead of writing something as (TRUE == (expression)), write it as (expression).
Instead of writing something as (FALSE == (expression)), write it as lways declare variables using the smallest scope possible.
Always declare a default: branch for a switch statement.
Always assign a pointer to NULL after deleting it.
If checking an expression and returning true or false based on the result, return the expression instead.
Goto statements are considered harmful.
When using an I/O stream, always use "<< endl" instead of "<< '\n'".
If you are going to typecast, use the casting operators (if available).
If the casting operators are unavailable, use the format "(type) (expression)".

Classes
When defining a class, always explicitly declare the private: section.
Always declare the protected: and public: sections, even if there is nothing in them.

When deriving one class from another class, explicitly declare the inheritance type, even if it is private.
Always overload the "friend ostream& operator <<" function and output the contents in a nice, readable format.
When overloading "operator <<", do not include leading or trailing whitespace (including endl!) in your implementation.
When defining a class, always make the header file which includes the class declaration as the first #included file.

Functions

It is acceptable to declare a function which is only called in one place.
If a function is more than 100 lines long, consider the use of sub-functions.
Always explicitly return from a function, even if it is a void function.
Always put parenthesis around the value being returned.
Try to design your functions so that they only have one return statement.

Files on Disk

A file with the extension of ".h" should generate no code or data.
A file with the extension of ".hpp" may generate code or data.
Limit the placement of one class per source file.
When a source file gets to be longer than 1000 lines, consider breaking it down into multiple source files.
Include whatever keyword is supported by your SCM system to tell you the file name, revision, author, etc. in each of your
source files.
Do not put path locations (relative or absolute) in #include statements.
Never require other files to be #included before any other #include file.
Always add a mechanism to prevent getting compiler errors if an include file is #included more than once.

Summary
Glossary

angle bracket
bracket
close bracket
culled
curly bracket
open bracket
parenthesis
square bracket
tome
vernacular

Introduction
Greetings! You are about to embark on a journey which will (well, we hope that it does, anyway) change how
you write code. Please note that what you are about to read in the pages of thistome is a collection of suggestions,
culled from the vast experience and code, both good and bad, from the Continuation Engineering department here

at NetSoft. While these guidelines will help to produce more readable and possibly more stable code, keep in
mind that they are just what we say: guidelines. There may be very good reasons to not follow certain guidelines
in some circumstances. Then don\u2019t. But adhering to these as much as possible will make all of our jobs a lot
easier.

"But why does it matter what it looks like? As long as it works, that\u2019s what matters." When you are writing a piece of software, you are
actually writing for two different audiences. Yes, one of them is the end user. Give yourself a pat on the back for that one. The other one
isn\u2019t always that obvious. But it happens to be you. It also happens to be us. That\u2019s right. It is whoever has to look at the code for
enhancements, maintenance, debugging, or trying to figure out what your code is doing. It is also why we use punctuation and
paragraphs in writing. It presents the information in a readable, easy-to-understand format which is familiar to you.

Here is how this document works: There are several major categories which will contain one or more recommendation. For each recommendation, an example will be provided showing the context of the recommendation. When a valid exception exists, it will also be shown in the example. As well as a functional example, a reason for doing it this way versus another will be provided.

Instead of making another dull document you have to suffer your way through, we tried to make this document fun to read. Through the use of humor, we are by no means negating the importance of one guideline versus another. Also, while reading, please remember that we are all human, and thereby prone to making errors. Please don\u2019t ridicule any bad grammar, spelling, or failed attempts at jokes. Thank you.

Guidelines
Identifiers

"So," you say, "just what do you mean by the word \u2018identifier\u2019?" Fair enough. Everyone has a certainvernacular they
are used to using, and you may not be familiar with a concept based on the words we use. For the purposes of this
document, the word "identifier" means "any token which is used to refer to a variable, function, class, type, etc." In
other words, it\u2019s what name you give to something. With that all said and done, let\u2019s start!

\u2022 Abbreviation is your enemy.

Despite what you may think, abbreviations are not always easy to understand. As well as being taxing on the person
trying to read the code, it is sometimes a headache for the person writing the code. "But wait," you\u2019re thinking (you
are, I can just tell). "The reason that I make something abbreviated is to make it easier on me." Most of the time, this is
a true statement. However, and I know that this has happened to me on more than one occasion, sometimes you can\u2019t
remember exactlyhow you abbreviated this one word. Now you have to go and find either another call into it, or the
definition itself. I believe that it is some derivation of Murphy\u2019s Law which states "If you don\u2019t remember the
abbreviation the first time, you are doomed to a lifetime of looking it up."

Example:
char ChrFrmUsr;
// Poor!
char Character_From_User;
// Great!
void GetVal (void);
// Get valid? Value?
void Get_Valium (void);
// Oh. I see now.
\u2022 When an identifier\u2019s name gets to be longer than 30 characters, consider renaming it.

Please note that in this document, we are using descriptive identifier names, not long ones. The fact that some of them are more than 15 characters derives from the fact that they are descriptive. Some problems with identifier names which are too long are:

\u2022
It becomes difficult to differentiate between two identifiers which have the same first 20 characters.
\u2022
The amount of useful information in one screen or paper width is more limited.
\u2022
It takes too long to type them.
Example:
char Character_Inputted_By_User_From_Keyboard; // Whoa! Bad!
char Character_From_User;
// Manageable, yet descriptive.
\u2022 U nd e r s c o re s _ a re _y o u r _ f r i e n ds .

When naming identifiers, it is difficult to read names where the words are all mashed together. In order to make
understanding what a variable is used for better, it is easiest to use a descriptive name, which may consist of multiple
words.

Example:
char characterfromuser;
// Could stand improvement...
char CharacterFromUser;
// Better...
char character_from_user;
// Better yet...
char Character_From_User;
// Excellent!
\u2022 Avoid using two underscores in a row.
The negative side to using an identifier with two consecutive underscores in it is that it is difficult to distinguish
between a single underscore versus two underscores in a row, especially in a proportional font.

You're Reading a Free Preview

Download
scribd
/*********** DO NOT ALTER ANYTHING BELOW THIS LINE ! ************/ var s_code=s.t();if(s_code)document.write(s_code)//-->