3DSoftwareRenderer-DFSPR/Doc/StyleGuide.txt

Code convention:
1. Use common sense!
	If it looks wrong to humans then it's wrong.
	Don't defeat the purpose of the rule by taking it too far.
2. Don't use iterators when there is any other way to accomplish the task.
	You can't write efficient algorithms without knowing the data structures.
3. Tabs for indentation then spaces for alignment.
	It's the best of both worlds by both having variable length tabs
	and correct alignment that works between lines of the same indentation.
	3.1. Do not use multiple spaces as a replacement for tabs in indentation.
	     I don't care if you set your editor to 2, 4 or 8 columns per tab
	     and neither should you care about my preferences.
	3.2. Do not use a tab as a replacement for multiple spaces in alignment.
	     The number of leading tabs should be equal to the indentation depth.
	     This way we can prove mathematically that blocks of code in the same
	     indentation will always keep the same relative alignment.
	3.3. Do not use tabs after spaces.
	     First tabs for indentation, then spaces for alignment.
	3.4. Do not try to align between different indentation depths.
	     Only align within the same depth so that it works for all tab lengths.
	Example using "--->" for tabs and "." for spaces:
		int foo(int x, int y) [
		--->if (superLongExpression(x) &&
		--->....superLongExpression(y)) {
		--->--->bar(x + y);
		--->}
		}
	If a reader uses 8 spaces per tab then superLongExpression is still aligned:
		int foo(int x, int y) [
		------->if (superLongExpression(x) &&
		------->....superLongExpression(y)) {
		------->------->bar(x + y);
		------->}
		}
4. No dangling else, use explicit {} for safety.
	Otherwise someone might add an extra statement and get random crashes.
5. No hpp extensions, use h for all headers.
	Could be either way, but this library uses *.h for compact naming, so keep it consistent.
6. C-style casting for raw data manipulation and C++-style for high-level classes.
	When using assembly intrinsics and raw pointer manipulation to alter the state of bits,
	verbose high-level abstractions only make it harder to count CPU cycles in your head.
	Always use the tool that makes sense for the problem you're trying to solve.
	C++ style is for things that are abstracted on a higher level.
	C style is for when a byte is just a byte and you just want to manipulate it in a specific way.
7. Don't call member methods with "this" set to nullptr.
	This would be undefined behaviour and may randomly crash.
	Use global functions instead. They allow checking pointers for null
	because they are explicit arguments declared by the programmer.
8. Avoid using STD/STL directly in SDK examples.
	Exposing types from the standard library should be done using an alias or wrapper in the dsr namespace.
	This allow replacing the standard library without breaking backward compatibility.
	The C++ standard have broken backward compatibility before and it can happen again.
9. Don't abuse the auto keyword everywhere just to make it look more "modern".
	Explicit type safety is what makes compiled languages safer than scripting.
10. No new line for opening brackets.
	Makes the code more compact and decreases the risk of copy-paste errors.
11. Don't fix the style of someone else's code if you can easily read it.
	Being pedantic can become an addiction consuming all your time.
	Fixing actual bugs and port to new systems is much more appreciated than
	causing version conflicts with others.
12. Don't change things that you don't know how to test.
	* Not doing enough regression tests will eventually create a mine-field of untested functions.
	  Regression testing will only slow down the amount of new bugs, unless you keep adding more regression tests.
	* Manual testing only finds bugs in code that's actually called by the program.
	  Two bugs may cancel each other out, which is common with negation and coordinate systems.
	* The larger the input is relative to the output, the lower coverage you will get from each test.
	  If your input is a video and the result is a boolean, any implementation has a 50% chance to pass the test on pure luck.
	  If your input is a boolean and the result is a video, you just try both cases and have full coverage.