Style Sheet - TecProgFGA-G10/postWar GitHub Wiki
- Function names must to be verbs.
- Variable and constant names must to be nouns.
- Constant and variable names must follow the pattern underscore_case.
- Variable names must be written on lower case.
int lives_left = 0;- Constant names must be in capital letters.
int const NUMBER_OF_LIVES = 3;- Variable, function and class names must be clear, unambiguous, and descriptive. Avoid abbreviations.
- All variables and constants must be declared one at a time so that a comment on the meaning of the variable can be provided.
int lives_left = 0; /* player's remaining lives */
double total_distance = 0; /* player’s total distance traveled */- All functions that return a bool should ask a true/false question, such as "is_visible()", or "should_clear_buffer()".
- Functions that return a value must describe the return value; the name must make clear what value the function will return. This is particularly important for boolean functions.
bool check_value(int value) {...} /* what does true mean? */
bool is_value_not_null(FTea Tea) {...} /* name makes it clear true means value is not null */- Only control variables can be named with just one letter. In these cases the letters “i” and “j” are recommended.
for (int i = 0; i <= lives_left; i++) {
/* nothing to do */
}- In vector and string names, must not have space between the variable name and the brackets; between the brackets and the inside numbers; and between the brackets.
int matrix[5][5] = 0;- Do not use hungarian notation.
char any_msg;
int i_nbr;- Remember that comments should augment the code. The code documents the implementation and the comments document the intent. Make sure to update comments when you change the intent of a piece of code.
- The style for comments is the C89 "/* ... */" style. Don't use C99-style "// ..." comments.
- The single-line comments should iniciate with lowercase letter. Exceptions are allowed, but avoid them if there is no good reason to.
/* this is a single-line comment */- The preferred style for long (multi-line) comments is:
/*
* This is the preferred style for multi-line
* comments in the source code.
* Please use it consistently.
*
* Description: A column of asterisks on the left side,
* with beginning and ending almost-blank lines.
*/- Write self-documenting code.
/* Bad: */
t = s + l + b;
/* Good: */
total_leaves = small_leaves + large_leaves - small_and_large_leaves;- Write useful comments.
/*
* Bad:
* increment leaves
*/
leaves = leaves + 1;
/*
* Good:
* we know there is another tea leaf
*/
leaves = leaves + 1;- Do not comment bad code - rewrite it.
/*
* Bad:
* total number of leaves is sum of
* small and large leaves less the
* number of leaves that are both
*/
t = s + l + b;
/* Good: */
total_leaves = small_leaves + large_leaves - small_and_large_leaves;- Do not contradict the code.
/*
* Bad:
* never increment leaves!
*/
leaves = leaves + 1;
/*
* Good:
* we know there is another tea leaf
*/
leaves = leaves + 1;- Do not use spaces after function names.
/* this is the wrong manner */
funcao (an_parameter, another_parameter);
/* this is the correct manner */
funcao(a_parameter, another_parameter);-
Use a space after these keywords: if, switch, case, for, do, while.
-
Do not use space after keyword that look somewhat like functions. E.g.: sizeof, typeof, alignof, or _attribute_.
-
Do not add spaces around (inside) parenthesized expressions.
/* the wrong manner */
s = sizeof( struct file );
/* the correct manner */
s = sizeof(struct file);- When declaring pointer data or a function that returns a pointer type, the preferred use of '*' is adjacent to the data name or function name and not adjacent to the type name.
/* correct pointer data declaration */
int *a_variable = NULL;
/* incorrect pointer data declarations */
int* another_variable
int * still_another_variable- Use one space around (on each side of) most binary and ternary operators.
/*
* Some binary and ternary operators:
* = + - < > * / % | & ^ <= >= == != ?
*\- Spaces can not be used after the unary operators.
/*
* Some unary operators:
* & * + - ~ ! sizeof typeof alignof __attribute__ defined
*\- Spaces can not be used before the postfix/prefix increment and decrement unary operators.
/* the wrong manners *\
i ++;
i --;
++ 1;
-- 1;
/* the correct manners *\
i++;
i--;
++1;
--1;- Spaces can not be used around the "." and "->" structure member operators.
- When using braces, put the opening brace last on the line with a space before, and put the closing brace first. This applies to all non-function statement blocks (if, switch, for, while, do).
if (condition) {
/* block code ommited */
}- There is one special case, namely functions: they have the opening brace at the beginning of the next line.
int function(int parameter)
{
/* body of function */
}- Do not leave trailing whitespace at the ends of lines.
- Always use braces even if will have just a single statement.
if (payment <= AVERAGE_PAYMENT) {
payment_bonus = payment * 0.10;
}
else {
payment_bonus = payment * 0.05;
}- A multi-way if statement should be indented with each else if indented the same amount as the first if.
if (condition) {
/* block code ommited */
}
else if (another_condition) {
/* block code ommited */
}
else {
/* block code ommited */
}- Indent code by execution block.
- Use tabs, not spaces, for whitespace at the beginning of a line. Set your tab size to 4 characters. However, spaces are sometimes necessary and allowed for keeping code aligned regardless of the number of spaces in a tab; e.g. when aligning code following non-tab characters.
- Must be used the double-indenting in the case labels.
- Except for empty cases (multiple cases having identical code), switch case statements should explicitly label that a case falls through to the next case. Either include a break or a falls-through comment in each case. Other code control-transfer commands (return, continue, etc.) are fine as well.
- Always have a default case, and include a break within.
switch (condition) {
case 1:
...
// falls through
case 2:
...
break;
case 3:
...
return;
case 4:
case 5:
...
break;
default:
break;
}- Do not use magic numbers. Declare a constant to be used instead of a number.`
const int unsigned MONTHS_QUANTITY = 12;
for (i = 0; i < MONTHS_QUANTITY ; i++) {
anual_salary = anual_salary + salary;
}- All variables must be initialized when declared, making clear their intention, even when the valor is changed after. The initial valor should be zero or null.
int lives_left = 0;
char player_name[SIZE_TEXT_FIELD] = {};- Minimize dependency distance. When code depends on a variable having a certain value, try to set that variable's value right before using it.
for (int i = 0; i <= [10]; i++) {
int number = 0; /* value setted only for initialization */
printf(“Type a number: ”);
scanf(“%d”, &number);
}- Prefer to use constants and variables locals instead of global ones.
- When declaring a variable or constant, always write a comment which specifies the unity of measure used.
const double WALL_HEIGHT = 3.14; /* width in meters */- When a method receives one variable that will not be changed, this must be declared as constant.
double const PAYMENT;- Wherever the variable will not assume negative values, it must be declared as unsigned.
int unsigned age = 1;- Split methods into sub-methods where possible.
- In function declarations or function call sites, do not add a space between the function's name and the parentheses that precedes the argument list.
- Address compiler warnings. Compiler warning messages mean something is not as it should be. Fix what the compiler is complaining about.
- Leave a blank line at the end of the file. All .c and .h files should include a blank line to play nice with gcc.
- Enforce encapsulation with the protection keywords. Class members should be declared private unless they are part of the public interface to the class.
- Use const wherever possible. Particularly on reference parameters and class methods. const is documentation as much as it is a compiler directive.
- Use intermediate variables to simplify complicated expressions. If you have a complicated expression, it can be easier to understand if you split it into sub-expressions that are assigned to intermediate variables with names describing the meaning of the sub-expression within the parent expression.
/* Bháskara */
/* Delta calculation */
double delta = pow(primary_term) 4 * quadratic_term * independent_term;
/* x’ calculation */
double x1 = (primary_term + sqrt(delta)) /
(2 * quadratic_term);
/* x’’ calculation */
double x2 = (primary_term sqrt(delta)) /
(2 * quadratic_term);