DCHECK fixes to mitigate 'unused variable' compiler errors.

Use Chromium's solution to the 'unused variable' compiler errors, when
compiling with DCHECKs turned off (i.e., simply reference the
expressions/variables in a no-op context). This prevents the need to add
extra preprocessor guards around blocks of code, and thus improves
compile-time error checking and unforeseen breakages in other build
configurations.

Also, fixes a typo where OSP_DCHECK_ALWAYS_ON was being tested (in
platform/api/logging.h), but it should be DCHECK_ALWAYS_ON (no "OSP_";
as set in the GN build config). Note that the build config was not,
instead, changed to OSP_DCHECK_ALWAYS_ON because of all the Chromium
third-party code that is switched by DCHECK_ALWAYS_ON (no "OSP_").

Change-Id: Ib81753248f0b03218c017143a22b991b4d8c63aa
Reviewed-on: https://chromium-review.googlesource.com/c/1450771
Reviewed-by: Yuri Wiitala <miu@chromium.org>
Commit-Queue: Yuri Wiitala <miu@chromium.org>

1 files changed, 26 insertions, 0 deletions

diff --git a/docs/style_guide.md b/docs/style_guide.md
index 00c71747..f55825c0 100644
--- a/docs/style_guide.md
+++ b/docs/style_guide.md
@@ -44,3 +44,29 @@ allowed, this declaration [enables STL optimizations](https://en.cppreference.co
 Blink style is *not allowed* anywhere in the Open Screen Library.
 
 C++17-only features are currently *not allowed* in the Open Screen Library.
+
+## OSP_CHECK and OSP_DCHECK
+
+These are provided in base/logging.h and act as run-time assertions (i.e., they
+test an expression, and crash the program if it evaluates as false). They are
+not only useful in determining correctness, but also serve as inline
+documentation of the assumptions being made in the code. They should be used in
+cases where they would fail only due to current or future coding errors.
+
+These should *not* be used to sanitize non-const data, or data otherwise derived
+from external inputs. Instead, one should code proper error-checking and
+handling for such things.
+
+OSP_CHECKs are "turned on" for all build types. However, OSP_DCHECKs are only
+"turned on" in Debug builds, or in any build where the "dcheck_always_on=true"
+GN argument is being used. In fact, at any time during development (including
+Release builds), it is highly recommended to use "dcheck_always_on=true" to
+catch bugs.
+
+When OSP_DCHECKs are "turned off" they effectively become code comments: All
+supported compilers will not generate any code, and they will automatically
+strip-out unused functions and constants referenced in OSP_DCHECK expressions
+(unless they are "extern" to the local module); and so there is absolutely no
+run-time/space overhead when the program runs. For this reason, a developer need
+not explicitly sprinkle "#if OSP_DCHECK_IS_ON()" guards all around any
+functions, variables, etc. that will be unused in "DCHECK off" builds.