This style guide is different from others you may see, because the focus is centered on readability and understandability.
1. Variable and method/function
1.1. Variable and method/function names that contain multiple characters must not start with an uppercase letter.
Further, each "word" within a variable name should start with an uppercase letter. For example,
campusMonitor are both appropriate variable names.
int maximumStudentSize = 100;
int max = 100; int maxsize = 100;
1.2. Variable names that consist of a single character may be uppercase.
In general, even single-character variable names should be lowercase. However, in some situations, mathematical notation uses uppercase letters. In such situations, uppercase variable names may be used. For example, matrices are often written using uppercase letters. So, an expression like (
b = A*x) would be appropriate.
1.3. Variable and method/function names must be descriptive.
Variable names like
aaa are not appropriate. Index variables and counters can, however, have names like
int getSumOfTwoNumber(int number1, int number2); void printSumOfTwoNumber(int number1, int number2);
Or you can use as
int getSumOfTwoNumber(int num1, int num2); void printSumOfTwoNumber(int num1, int num2);
int sum(int a, int b);
1.4. All variables must be declared at the top of the relevant function (with one exception).
The only exception to this rule is index variables in loops, which may be declared locally.
1.5. All variables must be declared alphabetically by their type.
For example, variables of type
double should be declared before variables of type
2. User-defined constants
User-defined constants must be entirely in uppercase.
#define MAXIMUM_STUDENT_SIZE 100; const int SIZE 32;
#define MAXIMUMSTUDENTSIZE 100; #define MaximumStudentSize 100; #define max 100; const int size 32;
3. Block comments
3.1 Block comments must start with /* and end with */.
3.2 Comments in the body of a function should use // rather than /* ... */.
This isn't a requirement but it will make your life easier since you can't nest comments inside of
/* ... */. There is nothing more annoying then trying to "comment out" a section of code while you are debugging and being unable to because it contains block comments.
3.3 Every file must begin with an appropriate comment block.
It must contain, at a minimum, the name of the file, its purpose, its author, the author's affiliation, and the date it was completed. For example:
/** * vectormath * * Purpose: This file contains functions for performing vector arithmetic. * * Author: Prof. David Bernstein, James Madison University * * Date: 15 January 1999 * * This work complies with the JMU Honor Code. */
3.4 Every function must begin with an appropriate comment block.
It must contain, at a minimum, the name of the method/function, its arguments (if any), side effects (if any), and what is returned (if anything).
/** * innerproduct * * Purpose: Calculate the inner product of two vectors. * * Arguments: vector1 One vector of doubles, vector2 The other vector of doubles * * Side Effects: None * * Returns: The inner (or dot) product */