Notesale: Turn your study into money

Document Preview

Extracts from the notes are below, to see the PDF you'll receive please use the links above

---

C/C++ Programming Style
Guidelines
Fred Richards
Style guidelines and programming practices for C/C++ code for
Dynamic Software Solutions
...

“ De gustibus non est disputandum
...
Introduction
This document contains the guidelines for writing C/C++ code for Dynamic Software
Solutions
...
The benefit is enhanced readability and hence maintainability for the
code
...

Before code can be considered for peer review the author must check that it adheres to
these guidelines
...
A
checklist is provided at the end of this document to aid in validating the source code’s
style
...

If you have not already, please study Code Complete by Steve McConnell
...
It also
includes references to statistical studies on many of the stylistic elements that affect
program maintainability
...
Kernighan and Rob Pike
...

And what person would be considered complete without having read The Elements of
Style by Strunk and White?

2
...
Each file should contain only one cohesive set of
functions
...
If different files contain
similar functions, consider generalizing the function sufficiently and putting it into its
own file so that both function groups can use the one source
...

Avoid strong coupling between functions and classes implemented in separate files
...

Use header files (
...
c,
...
cpp
suffix) to define implementations
...
Code that uses your
implementation will #include the header file
...
Explicitly include the
...
If, for example, your code calls a function defined
externally, include that function’s associated
...
h file
...
h file if
your public function interface or data type definitions require the definitions contained
therein
...
This “nesting” of #include constructs obscures file dependencies from
the reader
...
Unless the modules are cohesively coupled functionally, and each requires all the

...
h files everywhere they are required
...
1
...


1
...
Module abstract comment
3
...
Multiple inclusion #ifdef (a
...
a
...
Other preprocessor directives, #include and #define
6
...
Data type definitions (classes and structures)
8
...
Function declarations
10
...
Multiple inclusion #endif
Example 1
...
Richards
...

*
* Module for computing basic statistical measures on
* an array of real values
...
h>
#include ...

/*
* Compute the average of a given set
...

*
Output - average, 0 for empty array
...

#ifdef _cplusplus
}
#endif
#endif /* STATUS_H */

4

C/C++ Style Guide

2
...
Code Files
C and C++ code files follow a similar structure to the header files
...

1
...
Module abstract comment
3
...
Revision-string variable
5
...
Local function interface prototypes
7
...
This way ident will be able to identify the
source version from the compiled object file
...
This may be omitted for non-GNU projects
...


5

C/C++ Style Guide

Example 2
...
Richards
...

Module for computing basic statistical measures on
an array of real values
...
h"
#include
namespace {
const char rcs_id[] = "$Id$";
}
// Utility for prompting user for input
...


6

C/C++ Style Guide

3
...
If you use Emacs you can make this your default editing
mode by adding the following to your
...
Use blank
lines to help separate different ideas, use indentation to show logical relationships, and
use spaces to separate functionality
...

Start all function definitions and declarations in column zero
...
For functions that are more than a few lines long, put
the function name after the closing bracket in a comment
...
Formatting function declarations and definitions
void
debug(const string& message);
int
Class::method(const int x, const string& str)
{

...


...
The exceptions to this
rule are the “->”, “
...
Leave no space between these
operators and their operands
...

Use four spaces for each level of indentation
...
When breaking lines, use the natural logical breaks to determine where the
newline goes
...
For functions, for example, this means aligning arguments with
the opening parenthesis of the argument list
...
Breaking statements across multiple lines
new_shape = affine_transform(coords, translation,
rotation);
if ( ( (new_shape
...
x <
( (new_shape
...
y <
{
draw(new_shape);
}

left_border) &&
right_border) ) &&
bottom_border) &&
top_border) ) )

Use a pure-block, fully bracketed style for blocks of code
...
The exception to this rule is for
conditions that are broken across multiple lines
...

Example 5
...
");
}

Although the brackets may seem tedious for one-line blocks, they greatly reduce the
probability of errors being introduced when the block is expanded later in the code’s
life
...
1
...
Use explicit public labels for all struct public fields and use explicit
private labels for all private class members
...
Declare all public
data members and type definitions first
...
Declare all public member functions next, starting with the constructors and
destructor
...
Declare all private or protected function members next
...

Put simple inline function definitions on the same line as their declaration
...

In general, avoid putting complex function implementations
...

Example 6
...

void display() {

...
Choosing Meaningful Names
4
...
Variable Names
The name formatting conventions described here are essentially the GNU coding
standards
...

Use lower case for all variable names
...
Use all capitals for the names of constants (i
...
variables declared const and
enumerated types)
...

Choose variable names carefully
...
Review Chapter 9 of Code
Complete periodically
...

Use similar names for similar data types, dissimilar names for dissimilar types
...
g
...
Also, don’t rely on
capitalization to distinguish between variables
...
e
...


•

Avoid generic names such as tmp, buf, reg
...


In general, short names are acceptable for variables that serve a short-lived purpose or
that have a common usage in C/C++ (e
...
, index variables called i, j, k, etc
...
However, for variables that serve a
unique and important purpose, or variables that persist over a significant region of your
code, use descriptive and complete names
...


4
...
Function Names
Use lower-case letters for public function names
...

For functions that return no values (i
...
return type void), use strong verbs that indicate
the function’s purpose
...
For example,
void
remove_dc_offset(short *signal, const unsigned long length);
void
set_output_gain(const float gain);

Because functions tend to serve a more complex purpose than variables, longer names
are more acceptable
...
For instance,
/*
* Compute the DC offset of the given signal
...

*/
float
gain(void);

In general, be consistent and be informative
...


4
...
Classes, Structures and Type Definitions
The name formatting conventions described here are essentially those used by
Stroustrup in his book on C++
...
This includes all
struct, class, typedef and enum types
...

For class instance variables, start all names with lower-case letters
...
Apply the same rules to public and protected
members, both variables and functions
...


12

C/C++ Style Guide

Example 7
...

private:
int cached_x_;
// to avoid recomputing coordinates
int cached_y_;
};
// C++ usage example
Canvas sketch_pad;
sketch_pad
...

Remember that class members are identified by their class instance name
...

Example 8
...

template
class Stack {
public:
int stack_size;
add_item_to_stack(Type item);

...
add_item_to_stack(4);
int tmp = my_stack
...
Comments
In general, well written code should document itself
...
Occasionally, however, complex logic will
benefit from explicit description
...
If you find that your code requires many comments or is often
difficult to describe, perhaps you should be rewriting the code to make it simpler and
clearer
...
1
...
*/ style comments
...

style comments
...

Avoid the use of end-line comments except for variable declarations and for marking
#if/#endif statements
...
For longer
comments describing more complex logic, use a block style to offset them from the
code better
...
Use bold comments to
delimit major sections of your code file
...
The following example shows the various comment types in
the C style
...
C comment types
^L
/*
* ************************************************
* Bold comment
...

*/
/* Short (single-line) comment
...
2
...
Use a comment
to describe any variable whose purpose is not obvious from its name
...
Do not describe how your code works, that
should be obvious from the implementation
...
Avoid explaining especially tricky code in comments
...
Use complete sentences with proper spelling and
punctuation in all comments
...
If you start by
writing comments you give yourself a low-level design for the implementation
...

Comment things that have wide impact
...
If a required speed optimization makes
the code difficult to read, explain the need for the code in a comment
...

Use bold comments to delimit major sections in your code file
...
Use a bold comment to mark the start
of that code
...

There is no need to include the function name since it immediately follows the
comment
...
Commenting functions and function groups
^L

16

C/C++ Style Guide

/*
* ****************************************
* Statistics utilities used to
* optimize performance on the fly
...

*
* Input: v - set of values and set size
...

* Output: Dev = Expect (x - x_ave)^2
*
0 for the empty set
*/
static float
std_dev(const float *v, const unsigned long len)
{

...
This
applies to functions and conditional code
...

Use an end-line comment also to identify which #if or #ifdef statement a particular
#endif statement closes
...
When using #else conditions, mark both the #else
and the #endif statements with the negated condition (i
...
preface it with “not”)
...
Commenting long code blocks
#ifdef DEBUG

...


17

C/C++ Style Guide


...


...

} // position != END

...


...
Syntax and Language Issues
The following sections outline some general practices of good defensive programming
...
Also, assume that errors and defects are inevitable, and write so as
to isolate them and limit their effect as quickly as possible
...
Be liberal in checking the validity of input
arguments within functions, and always check values returned by functions you call
...
1
...
Each line should do exactly one
thing
...

Consider the following:
/* Bad practice! */
if (!eof && ((count = get_more()) > min_required) {

...

}
}

Avoid the use of side-effects
...


19

C/C++ Style Guide

Avoid type casts and never cast pointers to void*
...
If you feel the need to cast data
to other types in C++, perhaps you should be considering defining an inheritance
relationship or using templates
...
g
...

Avoid using preprocessor constants (i
...
#defines)
...
For related sets of integer constants,
define an enum
...

Limit variable scope as much as possible
...
Declare a variable just prior to using it and destroy it when
you are finished with it
...
Most people are
not intimately familiar with operator precedence, and parentheses can make logic
operations much easier for people to parse and understand
...
One of these things is not like the other
(x || y

&& y || z)

(x && y || z)
( (x && y) || z )
( (x || z) && (y || z) )

6
...
Structured Programming
Keep the structure of your code as clear as possible
...
Instead return with an appropriate error condition
...
Avoid using break and continue to escape
loop and branch code
...
Do not use goto
...
over the switch/case/case/
...
For both constructs use default conditions only to detect legitimate
defaults, or to generate an error condition when there is no default behavior
...

Prefer using while() {
...
} while();
...
The do {
...

Avoid overly long control structures
...
At the very least place a comment at the end of the structure to indicate the
exit conditions
...
Humans have a hard time keeping track of more than three
or four things at a time
...
Again, consider creating a new function if
you have too many embedded levels of logic in your code
...
They make your code hard to support in a
multi-threaded environment
...


6
...
Functions and Error Checking
Do not use preprocessor function macros
...
Define a function instead
...
h file for public functions or at the start of the
...
The function declaration list should read like a table of contents for your
code
...
Use
assertions to test for programming errors, use exceptions (C++) or return values (C) to
report error conditions detected in normal use
...
When a library function must report both a computed value and a distinct
error value, pass the computed value through a variable and return the error value
...
This is especially important for
functions providing access to system resources (e
...
, malloc(), fopen(), etc
...
Write messages that are understandable to the
user
...
Suggest possible
causes of the error condition
...
Conclusion
The guidelines presented here should be followed when writing all new code
...
Only if the coding style is ad hoc should you impose your own
(or these) conventions
...
It covers most of the items
discussed
...
Any
unaddressed issue is considered a coding defect during the review process
...
It can only ward
off some of the more flagrant problems
...
To that end, all C++ programmers should read Effective
C++, by Scott Meyers
...
It is critical for C++ programmers to understand these

22

C/C++ Style Guide

issues when writing new code
...
Review Checklist
File contents
...
e
...
h file?

•

Do function declarations/prototypes exist for all functions?

•

Does each code file contain exactly one cohesive set of classes or functions?

•

Are functions from different files sufficiently uncoupled from one another?

File format
...
, ->, [] and ()?

•

Do the C++ keywords public, private, protected, and friend all start in
column zero?

•

Are C++ class internals declared in the proper order?
1
...
private or protected data and types used in the class declaration
3
...
other private or protected data members
5
...
friends

Variable and function names
...

•

Are bold comments used to divide code into major sections? Are block comments
used to mark significant points? Are end-line comments used only for variable
declarations and to mark long blocks of code?

•

Does C++ code use //
...


•

Do all comments contain complete sentences, with proper punctuation and spelling?

•

Do comments describe intent rather than implementation details?

•

Is all subtle code sufficiently explained in comments?

•

Do all but the simplest functions have comments describing what they do, what data
they operate on and any impact they have on the rest of the application?

*/)?

Language usage
...
g
...
e
...

Code Complete: A Practical Handbook of Software Construction, Code Complete,
Steve McConnell, 1-55615-484-4, Microsoft Press, 1993
...

The Elements of Style, William Strunk, Jr
...
B
...
, Inc
...

More Effective C++: 35 New Ways to Improve Your Programs and Designs, More
Effective C++, Scott Meyers, 0-201-63371-X, 1996, Addison-Wesley, 1998
...
Kernighan and Rob Pike, 0-201-61586-X,
Addison-Wesley, 1999

---

Title: c & C++ programming
Description: this is the detailed notes for C & C++ programming, very useful for everyone.

Buy These NotesPreview