Browse Source

Simplified documents that sounded a bit confusing.

David Piuva 5 years ago
parent
commit
111403cebe
2 changed files with 23 additions and 25 deletions
  1. 4 9
      Doc/GettingStarted.txt
  2. 19 16
      Doc/StyleGuide.txt

+ 4 - 9
Doc/GettingStarted.txt

@@ -1,27 +1,22 @@
-LINUX
-
 Place the library's root folder inside of a new folder.
 This allow keeping your own projects and the "temporary" folder that's
 used for compiling quickly outside of the library's version history.
 
-If using Linux with an X11 server, you might need to install the X11 headers.
+If using Linux, you might need to install the X11 headers.
 If it doesn't work, your Linux distro might not have an X11 server.
 On debian based distributions:
 	sudo apt-get install libx11-dev
 
-If using a Raspberry Pi, you can use Raspbian (Buster or newer for X11 support) or Ubuntu Mate with the following performance tweaks:
-	Control panel - Sound - Activate sound for windows and buttons: Off
-	Firefox browser - Preferences - General - Use smooth scrolling: Off
-	Firefox browser - Preferences - Home - Homepage and new windows: Blank page
+If using a Raspberry Pi, you can use Raspbian (Buster or newer for X11 support) or Ubuntu Mate.
 
-Build and run an example program:
+Build and run an example program on Linux:
 	* Select an SDK example and open its folder in a terminal.
 	* Give permission to execute the build script.
 		chmod +x build.sh
 	* Run the build script.
 		./build.sh
 
-Run regression tests:
+Run regression tests on Linux:
 	* Open the source folder in a terminal and run the test script:
 		chmod +x test.sh
 		./test.sh

+ 19 - 16
Doc/StyleGuide.txt

@@ -35,32 +35,35 @@ Code convention:
 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.
-	Use macros if you want to use the same API for both C and C++,
-	so that it selects the correct version for the language automatically.
-6. C-style casting for raw data manipulation and C++-style for polymorphism.
-	C++-style casting makes no sense when using assembly intrinsics.
-	High-level behaviour is undefined behaviour in bare metal programming
-	and only adds more confusion when trying to optimize code.
+	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.
-	Use the safer and faster wrapper types in the dsr namespace.
-	One shouldn't have to remember which namespace a collection was declared in.
+	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".
-	Auto can decrease readability if used too often.
-	Don't force the reader to look into multiple modules to figure out the type.
+	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 manually.
-
-Regression tests can only catch a percentage of new defects and
-cannot guarantee any level of quality on its own for a large test space.
-The principle of random sampling to estimate quality is only valid
-if the samples are actually random to cover the entire test space.
+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.