No Description

Nicolás A. Ortega 4bd82c2fcd Return values in parameters added.		7 years ago
README.md	4bd82c2fcd Return values in parameters added.	7 years ago

Rational Code Style

This is a README-only repository that exposes what coding style should be used for what rational reasons. Everyone has preferences, and these are aside from reason, however there are certain rational reasons to use certain coding styles. If you have counter rationale or evidence suggesting a different style may be better overall then feel free to contribute.

Brackets
Indentation
- Width
- Whitespace
Statements Per Line
License

Brackets

The most rational (or rather, practical) way of using brackets is broken, not attached. Of course, this only applies when discussing conditionals and loops. The reason for this is so that it is easy to, for example, only run through a loop once, or to unconditionally run a group of code, simply by commenting out one line of code. For example, what if we were to make a conditional statement unconditional:

//if(condition)
{
	// code here ...
}

versus

/*if(condition)*/ {
	// code here ...
}

//if(condition) {
	// code here ...
//}

As you can see, the first example is much more simple, only requiring us to comment out one line, while the second example requires you to use block commenting in order to select a specific part of the line to comment out. The third example has the additional issue that it broadens the scope of the code which may not be desirable and will be doing more than simply making the code unconditional.

Of course, this does not apply to other uses of brackets such as in function definitions, enumerations, structures, or anything else. What's more, in switch cases this does not apply either. However, for consistency's sake one may wish to have all brackets broken.

By this same logic, else and else if statements should not be written on the same line as the closing curly brace of the previous if statement. That is:

if(condition0)
{
	// code here ...
}
else if(condition1)
{
	// code here ...
}
else
{

}

instead of

if(condition0) {
	// code here ...
} else if(condition1) {
	// code here ...
} else {
	// code here ...
}

Indentation

Width

There is very little research to indicate the best indentation width which may be objectively better for reading code. There are some sources that suggest that both 2 and 4 are generally easy to read while a width of 0 or 6 significantly hinder performance. However, these studies tend to be very limited. Other sources give other reasoning for using 2 or 4 width indentation at least in object oriented languages (namely Java or C#).

Whitespace

The two camps in this eternal feud are tabs and spaces. Follows are a list of reasons why each is useful:

Spaces:
- Everyone sees the same indentation
- Helps reduce mixing of whitespace characters (when tabs are allowed different whitespace can often be mixed quite accidentally)
Tabs:
- Everyone sees the indentation they are accustomed to
- One character therefore reducing file size (although in the era of 2TB hard drives for laptops this is quite insignificant)

With this in mind, it depends on what is important for your project. However, if you would like for everyone to be able to read with the indentation width that they are most accustomed to then use tabs.

This being said, even those who use tabs agree that spaces should be used when aligning operators or anything of the kind, however that does not have to do with indentation of code instructions.

Statements Per Line

For similar reasons to the Brackets section, you should always have one statement per line. Imagine that you wish to make a conditional statement or a loop with only one instruction into an unconditional or have the loop run only once. In this circumstance the code would look as follows:

//if(condition)
	// code here ...

versus

/*if(condition)*/ // code here ...

As can be seen, the first example is much easier to comment out than the second.

This can also be applied to using return values of a function as something other than assignment. For example:

myFunction(
	returnSomeValue());