diff options
Diffstat (limited to 'docs/style_guide.md')
| -rw-r--r-- | docs/style_guide.md | 26 |
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. |