mirror of
https://github.com/matrix-construct/construct
synced 2024-11-24 15:52:34 +01:00
Various updates; remove unnecessary sections.
parent
5a9c31c24f
commit
535e84357c
1 changed files with 11 additions and 53 deletions
64
STYLE.md
64
STYLE.md
|
@ -258,13 +258,6 @@ other words, if you have a prototype like `foo(const std::string &message)` you
|
||||||
OTOH, if you have `foo(const options &options, const std::string &message)` one should skip
|
OTOH, if you have `foo(const options &options, const std::string &message)` one should skip
|
||||||
the name for `options &` as it just adds redundant text to the prototype.
|
the name for `options &` as it just adds redundant text to the prototype.
|
||||||
|
|
||||||
* Consider any code inside a runtime `assert()` statement to **entirely**
|
|
||||||
disappear in optimized builds. If some implementations of `assert()` may only
|
|
||||||
elide the boolean check and thus preserve the inner statement and the effects
|
|
||||||
of its execution: this is not standard; we do not rely on this. Do not use
|
|
||||||
`assert()` to check return values of statements that need to be executed in
|
|
||||||
optimized builds.
|
|
||||||
|
|
||||||
|
|
||||||
#### Comments
|
#### Comments
|
||||||
|
|
||||||
|
@ -320,7 +313,7 @@ line starting with `//` with no text after it. Combined with the allowed
|
||||||
completely blank line after that you now have more whitespace.
|
completely blank line after that you now have more whitespace.
|
||||||
|
|
||||||
|
|
||||||
### Conventions
|
## Conventions
|
||||||
|
|
||||||
These are things you should know when mulling over the code as a whole. Knowing
|
These are things you should know when mulling over the code as a whole. Knowing
|
||||||
these things will help you avoid various gotchas and not waste your tim
|
these things will help you avoid various gotchas and not waste your tim
|
||||||
|
@ -354,32 +347,6 @@ which count characters printed *not including null*. They may return a
|
||||||
`string_view`/`const_buffer` of that size (never viewing the null).
|
`string_view`/`const_buffer` of that size (never viewing the null).
|
||||||
|
|
||||||
|
|
||||||
#### Iteration protocols
|
|
||||||
|
|
||||||
When not using STL-iterators, you may encounter some closure/callback-based
|
|
||||||
iterator functions. Usually that's a `for_each()`. If we want to break out
|
|
||||||
of the loop, our conventions are as follows:
|
|
||||||
|
|
||||||
- *find protocol* for `find()` functions. The closure returns true to break
|
|
||||||
the loop at that element, false to continue. The `find()` function itself
|
|
||||||
then returns a pointer or reference to that element. If the end of the
|
|
||||||
iteration is reached then a `find()` usually returns `nullptr` or throws an
|
|
||||||
exception, etc.
|
|
||||||
|
|
||||||
- *test protocol* for `test()` functions (this has nothing to do with unit-
|
|
||||||
tests or development testing). This is the same logic as the find protocol
|
|
||||||
except the `test()` function itself returns true if the closure broke the
|
|
||||||
loop by returning true, or false if the end of the iteration was reached.
|
|
||||||
|
|
||||||
- *until protocol* for `until()` functions. The closure "remains true 'till
|
|
||||||
the end." When the end is reached, true is returned. The closure returns false
|
|
||||||
to break the loop, and then false is returned from until() as well.
|
|
||||||
|
|
||||||
Overloads of `for_each()` may be encountered accepting closures that return
|
|
||||||
`void` and others that return `bool`. The `bool` overloads use the
|
|
||||||
*until protocol* as that matches the same logic in a `for(; bool;)` loop.
|
|
||||||
|
|
||||||
|
|
||||||
#### nothrow is not noexcept
|
#### nothrow is not noexcept
|
||||||
|
|
||||||
Often a function is overloaded with an std::nothrow_t argument or our
|
Often a function is overloaded with an std::nothrow_t argument or our
|
||||||
|
@ -388,26 +355,17 @@ a specific exception expected from the overload alternative** (or set of
|
||||||
exceptions, etc). Any exception may still come out of that nothrow overload;
|
exceptions, etc). Any exception may still come out of that nothrow overload;
|
||||||
technically including the specific exception if it came from somewhere else!
|
technically including the specific exception if it came from somewhere else!
|
||||||
|
|
||||||
Use the noexcept keyword with tact, not by default. Most of the project
|
The `noexcept` specifier is employed to mark non-inline functions which don't
|
||||||
propagates exceptions. Functions that handle their errors and are expected to
|
throw; we elide `noexcept` for inline functions which don't throw unless there
|
||||||
return (i.e since they catch `std::exception`), still throw special exceptions
|
is an explicit reason for it. The former provides valuable information to the
|
||||||
like `ircd::ctx::terminated`. If the `catch(...)` and `noexcept` features are
|
compiler affecting optimization around calls where the compiler can't see
|
||||||
used: developers must cooperate by handling ctx interruptions and propagating
|
the callee's implementation to deduce it doesn't throw.
|
||||||
terminations. This is not an issue on leaf and simple functions where we tend
|
|
||||||
to make use of `noexcept`, especially for non-inlines allowing for better
|
|
||||||
compiler optimizations to occur.
|
|
||||||
|
|
||||||
|
Most of the project propagates exceptions. Functions that handle their errors
|
||||||
#### Indications of yielding and IO's
|
and are expected to return (i.e since they catch `std::exception`), still throw
|
||||||
|
special exceptions like `ircd::ctx::terminated`. If the `catch(...)` and
|
||||||
There is a section on how yielding and IO can occur far up the stack from a
|
`noexcept` features are used: developers must cooperate by handling ctx
|
||||||
benign-looking callsite in ctx/README. We try to make comments to indicate
|
interruptions and propagating terminations.
|
||||||
these things directly in the definitions and certainly in documentation.
|
|
||||||
|
|
||||||
Some of those indications may say nothing more than `[GET]` and `[SET]` without
|
|
||||||
any other comment. That is the minimum acceptable marking for something which
|
|
||||||
will likely do read or write IO respectively to disk or even the network. In
|
|
||||||
any such case the ircd::ctx will definitely yield if that happens.
|
|
||||||
|
|
||||||
|
|
||||||
#### Nothing ticks
|
#### Nothing ticks
|
||||||
|
|
Loading…
Reference in a new issue