Difference between revisions of "Standards for Programming Style"

From David Vernon's Wiki
Jump to: navigation, search
 
(19 intermediate revisions by the same user not shown)
Line 1: Line 1:
<strong>WORK IN PROGRESS ... DON'T READ</STRONG>
 
 
 
== Indentation and Line Breaks ==
 
== Indentation and Line Breaks ==
 
Either three or four spaces should be used as the unit of indentation. Choose one standard and stick to it throughout the code.
 
Either three or four spaces should be used as the unit of indentation. Choose one standard and stick to it throughout the code.
  
  
Do not use tabs to indent text. If you are using Microsoft Visual C++ turn off the tabs option (go to Tools -> Options -> Text Editor -> C/C+ -> Tabs+ and click the insert spaces radio button; you can set the number of spaces to three or four here too).
+
Do not use tabs to indent text. If you are using Microsoft Visual C++ turn off the tabs option (go to Tools -> Options -> Text Editor -> C/C++ -> Tabs and click the insert spaces radio button; you can set the number of spaces to three or four here too).
  
  
Line 38: Line 36:
 
Do not put different types on the same line:
 
Do not put different types on the same line:
  
  int foo, fooarray[]; //WRONG!
+
int foo, fooarray[]; //WRONG!
  
 
===Initialization===
 
===Initialization===
 
Initialize local variables where they are declared. The only reason not to initialize a variable where it’s declared is if the initial value depends on some computation occurring first.
 
Initialize local variables where they are declared. The only reason not to initialize a variable where it’s declared is if the initial value depends on some computation occurring first.
 
  
 
==Placement==
 
==Placement==
Line 49: Line 46:
  
 
  void myMethod() {
 
  void myMethod() {
  int int1 = 0; // beginning of method block
+
    int int1 = 0; // beginning of method block
  if (condition) {
+
    if (condition) {
      int int2 = 0; // beginning of "if" block
+
      int int2 = 0; // beginning of "if" block
      ...
+
      ...
  }  
+
    }  
}
+
}
  
 
===Class Declarations===
 
===Class Declarations===
Line 95: Line 92:
 
A return statement with a value should not use parentheses unless they make the return value more obvious in some way. For example:
 
A return statement with a value should not use parentheses unless they make the return value more obvious in some way. For example:
  
  return;
+
return;
  return myDisk.size();
+
return myDisk.size();
  return TRUE;
+
return TRUE;
  
 
<code>if,if-else,if else-if else</code> Statements
 
<code>if,if-else,if else-if else</code> Statements
Line 173: Line 170:
  
 
===C vs. C++===
 
===C vs. C++===
Naming conventions make programs more understandable by making them easier to read. Since DREAM software uses both the C language and the C++ language, sometimes using the imperative programming and object-oriented programming paradigms separately, sometimes using them together, we will adopt two different naming conventions, one for C and the other for C++. The naming conventions for C++ are derived from the JavaDoc standards.
+
Naming conventions make programs more understandable by making them easier to read. Since CINDY software uses both the C language and the C++ language, sometimes using the imperative programming and object-oriented programming paradigms separately, sometimes using them together, we will adopt two different naming conventions, one for C and the other for C++. The naming conventions for C++ are derived from the JavaDoc standards.
  
 
===C++ Language Conventions===
 
===C++ Language Conventions===
Line 179: Line 176:
 
The following are the naming conventions for identifiers when using C++ and the object-oriented paradigm.
 
The following are the naming conventions for identifiers when using C++ and the object-oriented paradigm.
  
Identifier Type & Rules for Naming                                   &Examples                                 \\ \hline
+
{|
Classes        & Class names should be nouns, in mixed case with   &\verb+class ImageDisplay+                \\
+
|'''Identifier Type'''  ||  '''Rules for Naming '''                                  || '''Examples''' 
                & the first letter of each internal word capitalized &\verb+class MotorController+            \\
+
|-
                &                                                   &                                        \\
+
|Classes        ||Class names should be nouns, in mixed case with     || <code>class ImageDisplay</code> 
Methods        & Method names should be verbs, in mixed case with  &\verb+int grabImage()+                  \\
+
|-           
                & the first letter in lowercase, with the first      &\verb+int setVelocity()+                \\
+
|                || the first letter of each internal word capitalized || <code>class MotorController</code> 
                & letter of each internal word capitalized          &                                         \\
+
|-           
                &                                                   &                                         \\
+
|                ||                                                   ||                             
Variables      & variable names should be in mixed case with the    &{\small \verb+int    i;+}                \\
+
|-         
                & first letter in lowercase, with the first letter  &{\small \verb+float  f;+}               \\
+
|Methods        || Method names should be verbs, in mixed case with  || <code>int grabImage()</code>   
                & of each internal word capitalized                  &{\small \verb+double pixelValue;+}       \\
+
|-               
                &                                                   &                                        \\
+
|                || the first letter in lowercase, with the first      || <code>int setVelocity()</code> 
Constants      & The names of variables declared as constants      &{\small \verb+const int WIDTH = 4;+}    \\
+
|-               
                & should be all uppercase with words separated by    &                                        \\
+
|                || letter of each internal word capitalized          ||
                & underscores {\small \verb+_+}                      &                                         \\
+
|-                                          
                &                                                   &                                         \\
+
|                ||                                                   ||
Type Names      & Typedef names should use the same naming policy as &{\small \verb+typedef uint16 ComponentType+}\\
+
|-                                          
                & that used for class names                          &                                        \\
+
|Variables      || variable names should be in mixed case with the    || <code>int    i;</code>
                &                                                   &                                        \\
+
|-             
Enum Names      & Enum names should use the same naming policy as    &{\small \verb+enum PinState {+}         \\
+
|                || first letter in lowercase, with the first letter  || <code>float  f;</code>
                & that used for class names.                        &{\small \verb+  PIN_OFF,+}              \\
+
|-             
                & Enum labels should should be all uppercase with    &{\small \verb+  PIN_ON  +}              \\
+
|               || of each internal word capitalized                  || <code>double pixelValue;</code>
                & words separated by underscores \verb+_+            &{\small \verb+};+}                       \\
+
|-        
 +
|                ||                                                   ||                       
 +
|-                 
 +
|Constants      || The names of variables declared as constants      || <code>const int WIDTH = 4;</code>
 +
|- 
 +
|                || should be all uppercase with words separated by    || 
 +
|-                                       
 +
|                || underscores <code>_</code>                        ||
 +
|-                                          
 +
|                ||                                                   ||
 +
|-                                          
 +
|Type Names      || Typedef names should use the same naming policy as || <code>typedef uint16 ComponentType</code>
 +
|-
 +
|                || that used for class names                          ||     
 +
|-                                 
 +
|                ||                                                   ||   
 +
|-                                   
 +
|Enum Names      || Enum names should use the same naming policy as    || <code>enum PinState {</code>
 +
|-          
 +
|                || that used for class names.                        || <code>PIN_OFF,</code>
 +
|-           
 +
|                || Enum labels should should be all uppercase with    || <code> PIN_ON  /code>
 +
|-           
 +
|                || words separated by underscores <code>_</code>      ||  <code>};</code>     
 +
|}               
 +
 +
===C Language Conventions===
 +
The following are the naming conventions for identifies when using C and the imperative programming paradigm.
 +
 +
{|
 +
|Identifier Type ||  Rules for Naming                                  || Examples           
 +
|- 
 +
|Functions      ||  Function names should be all lowercase with words  || <code>int  display_image()</code>   
 +
|- 
 +
|                ||  separated by underscores <code>_</code>        || <code>void set_motor_control()</code>
 +
|- 
 +
|                ||                                                    ||                                         
 +
|- 
 +
|Variables      ||  variable names should be all lowercase with words  || <code>int    i;</code>     
 +
|-       
 +
|                ||  separated by underscores <code>_</code>      || <code>float  f;</code>   
 +
|-         
 +
|                ||  of each internal word capitalized                  || <code>double pixel_value;</code>
 +
|-   
 +
|                ||                                                    ||               
 +
|-                         
 +
|Constants      ||  Constants should be all uppercase with words      || <code>#define WIDTH 4</code>
 +
|-       
 +
|                ||  separated by underscores <code>_</code>}      ||           
 +
|-                               
 +
|                ||                                                    ||                               
 +
|-           
 +
|<code>#define</code>  ||  <code>#define</code> and macro names should all uppercase|| <code>#define SUB(a,b) ((a) - (b))</code> 
 +
|- 
 +
|and Macros      ||  with words separated by underscores <code>_</code>      || 
 +
|- 
 +
|}
  
 
+
===And Finally: Where To Put The Opening Brace <code>{</code>===
D3.2 Software Engineering Standards
+
EnumNames  Enumnamesshouldusethesamenamingpolicyas that used for class names.
+
Enum labels should should be all uppercase with words separated by underscores _
+
C Language Conventions
+
The following are the naming conventions for identifies when using C and the imperative program- ming paradigm.
+
Identifier Type Functions
+
Variables
+
Constants
+
#define
+
and Macros
+
Rules for Naming
+
Function names should be all lowercase with words separatedbyunderscores_
+
variable names should be all lowercase with words separated by underscores _ ofeachinternalwordcapitalized
+
Constantsshouldbealluppercasewithwords separated by underscores _
+
#defineandmacronamesshouldalluppercase with words separated by underscores _
+
Examples
+
int  display_image()
+
void set_motor_control()
+
int    i;
+
float  f;
+
double pixel_value;
+
#define WIDTH 4
+
#define SUB(a,b) ((a) - (b))
+
D.6 And Finally: Where To Put The Opening Brace {
+
 
There are two main conventions on where to put the opening brace of a block. In this document, we have adopted the JavaDoc convention and put the brace on the same line as the statement preceding the block. For example:
 
There are two main conventions on where to put the opening brace of a block. In this document, we have adopted the JavaDoc convention and put the brace on the same line as the statement preceding the block. For example:
  
class Sample {
+
class Sample {
  ...
+
    ...
}
+
}
while (condition) {
+
  statements;
+
while (condition) {
}
+
    statements;
 +
}
 +
 
 
The second convention is to place the brace on the line below the statement preceding the block and it indent it to the same level. For example:
 
The second convention is to place the brace on the line below the statement preceding the block and it indent it to the same level. For example:
  class Sample
+
 
  {
+
class Sample
... }
+
{
  while (condition)
+
    ...  
  {
+
}
      statements;
+
  }
+
while (condition)
If you really hate the JavaDoc format, use the second format, but be consistent and stick to it through- out your code.
+
{
 +
    statements;
 +
}
 +
 
 +
If you really hate the JavaDoc format, use the second format, but be consistent and stick to it throughout your code.

Latest revision as of 04:46, 20 January 2020

Indentation and Line Breaks

Either three or four spaces should be used as the unit of indentation. Choose one standard and stick to it throughout the code.


Do not use tabs to indent text. If you are using Microsoft Visual C++ turn off the tabs option (go to Tools -> Options -> Text Editor -> C/C++ -> Tabs and click the insert spaces radio button; you can set the number of spaces to three or four here too).


Avoid lines longer than 80 characters, since they are not handled well by many terminals and tools.


When an expression will not fit on a single line, break it according to the following general principles.

  • Break after a comma.
  • Break before an operator.
  • Align the new line with the beginning of the expression at the same level on the previous line.

For example, consider the following statements.

longName1 = longName2 * (longName3 + longName4 - longName5)
            + 4 * longName6;  // Good break
longName1 = longName2 * (longName3 + longName4
                         - longName5) + 4 * longName6;  // bad break: avoid

Declarations

Number Per Line

One declaration per line is recommended since it encourages commenting:

int level; // indentation level
int size;  // size of table

is preferable to:

int level, size;

Do not put different types on the same line:

int foo, fooarray[]; //WRONG!

Initialization

Initialize local variables where they are declared. The only reason not to initialize a variable where it’s declared is if the initial value depends on some computation occurring first.

Placement

Put declarations only at the beginning of blocks. A block is any code surrounded by curly braces { and }. Don’t wait to declare variables until their first use. Ideally, declare all variables at the beginning of the method or function block.

void myMethod() {
   int int1 = 0; // beginning of method block
   if (condition) {
      int int2 = 0; // beginning of "if" block
      ...
   } 
}

Class Declarations

The following formatting rules should be followed:

  • No space between a method name and the parenthesis ( starting its parameter list.
  • The open brace { appears at the end of the same line as the declaration statement.
  • Theclosingbrace}startsalinebyitselfindentedtomatchitscorrespondingopeningstatement.
class Sample {
        ...
}
  • Methods are separated by a blank line

Statements

Simple Statements

Each line should contain at most one statement. For example:

argv++;         // Correct
argc++;         // Correct
argv++; argc--; // AVOID!

Compound Statements

Compound statements are statements that contain lists of statements enclosed in braces { statements }. See the following sections for examples.

  • The enclosed statements should be indented one more level than the compound statement.
  • The opening brace should be at the end of the line that begins the compound statement; the closing brace should begin a line and be indented to the beginning of the compound statement.
  • Braces are used around all statements, even single statements, when they are part of a control structure, such as a if-else or for statement. This makes it easier to add statements without accidentally introducing bugs due to forgetting to add braces.
if (condition) {
   a = b;
}
else {
   a = c; 
}

return Statements A return statement with a value should not use parentheses unless they make the return value more obvious in some way. For example:

return;
return myDisk.size();
return TRUE;

if,if-else,if else-if else Statements The if-else class of statements should have the following form:

if (condition) {
   statements;
}

if (condition) {
   statements;
} else {
   statements;
}
 
if (condition) {
   statements;
} else if (condition) {
   statements;
} else {
  statements;
}

Always use braces { }, with if statements. Don’t use

if (condition) //AVOID!
   statement;

for Statements A for statement should have the following form:

for (initialization; condition; update) {
   statements;
}

while Statements

A while statement should have the following form:

while (condition) {  
   statements;
}

do-while Statements A do-while statement should have the following form:

do {
   statements;
} while (condition);

switch Statements A switch statement should have the following form:

switch (condition) {
case ABC:
   statements;
    /* falls through */
case DEF:
   statements;
   break;
case XYZ:
   statements;
   break;
default:
   statements;
  break; 
}

Every time a case falls through (i.e. when it doesn’t include a break statement), add a comment where the break statement would normally be. This is shown in the preceding code example with the /* falls through */ comment.


Every switch statement should include a default case. The break in the default case is redundant, but it prevents a fall-through error if later another case is added.

Naming Conventions

C vs. C++

Naming conventions make programs more understandable by making them easier to read. Since CINDY software uses both the C language and the C++ language, sometimes using the imperative programming and object-oriented programming paradigms separately, sometimes using them together, we will adopt two different naming conventions, one for C and the other for C++. The naming conventions for C++ are derived from the JavaDoc standards.

C++ Language Conventions

The following are the naming conventions for identifiers when using C++ and the object-oriented paradigm.

Identifier Type Rules for Naming Examples
Classes Class names should be nouns, in mixed case with class ImageDisplay
the first letter of each internal word capitalized class MotorController
Methods Method names should be verbs, in mixed case with int grabImage()
the first letter in lowercase, with the first int setVelocity()
letter of each internal word capitalized
Variables variable names should be in mixed case with the int i;
first letter in lowercase, with the first letter float f;
of each internal word capitalized double pixelValue;
Constants The names of variables declared as constants const int WIDTH = 4;
should be all uppercase with words separated by
underscores _
Type Names Typedef names should use the same naming policy as typedef uint16 ComponentType
that used for class names
Enum Names Enum names should use the same naming policy as enum PinState {
that used for class names. PIN_OFF,
Enum labels should should be all uppercase with PIN_ON /code>
words separated by underscores <code>_ };

C Language Conventions

The following are the naming conventions for identifies when using C and the imperative programming paradigm. 

Identifier Type Rules for Naming Examples
Functions Function names should be all lowercase with words int display_image()
separated by underscores _ void set_motor_control()
Variables variable names should be all lowercase with words int i;
separated by underscores _ float f;
of each internal word capitalized double pixel_value;
Constants Constants should be all uppercase with words #define WIDTH 4
separated by underscores _}
#define #define and macro names should all uppercase #define SUB(a,b) ((a) - (b))
and Macros with words separated by underscores _

And Finally: Where To Put The Opening Brace {

There are two main conventions on where to put the opening brace of a block. In this document, we have adopted the JavaDoc convention and put the brace on the same line as the statement preceding the block. For example:

class Sample {
   ...
}

while (condition) {
   statements;
}

The second convention is to place the brace on the line below the statement preceding the block and it indent it to the same level. For example:

class Sample
{
   ... 
}

while (condition)
{
   statements;
}

If you really hate the JavaDoc format, use the second format, but be consistent and stick to it throughout your code.