diff --git a/STYLE.md b/STYLE.md index 46bc2970d6eaa..61223e9456da0 100644 --- a/STYLE.md +++ b/STYLE.md @@ -30,7 +30,10 @@ fiasco](https://isocpp.org/wiki/faq/ctors#static-init-order-on-first-use) for how to best handle this. * API-level comments should follow normal Doxygen conventions. Use `@param` to describe - parameters, `@return ` for return values. + parameters and `@return ` for return values. Internal comments for + methods and member variables may be regular C++ `//` comments or Doxygen at + developer discretion. Where possible, methods should have meaningful + documentation on expected input and state preconditions. * Header guards should use `#pragma once`. * There are probably a few other things missing from this list. We will add them as they are brought to our attention. @@ -91,7 +94,7 @@ A few general notes on our error handling philosophy: `RELEASE_ASSERT` as the uncommon case, but experience and judgment may dictate a particular approach depending on the situation. -# Hermetic tests +# Hermetic and deterministic tests Tests should be hermetic, i.e. have all dependencies explicitly captured and not depend on the local environment. In general, there should be no non-local network access. In addition: @@ -111,6 +114,11 @@ environment. In general, there should be no non-local network access. In additio `{{ test_udsdir }}` is provided for pathname based Unix Domain Sockets, which must fit within a 108 character limit on Linux, a property that might not hold for `{{ test_tmpdir }}`. +Tests should be deterministic. They should not rely on randomness or details +such as the current time. Instead, mocks such as +[`MockRandomGenerator`](test/mocks/runtime/mocks.h) and +[`Mock*TimeSource`](test/mocks/common.h) should be used. + # Google style guides for other languages * [Python](https://google.github.io/styleguide/pyguide.html)