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
|
||||
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
|
||||
|
||||
|
@ -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.
|
||||
|
||||
|
||||
### Conventions
|
||||
## Conventions
|
||||
|
||||
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
|
||||
|
@ -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).
|
||||
|
||||
|
||||
#### 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
|
||||
|
||||
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;
|
||||
technically including the specific exception if it came from somewhere else!
|
||||
|
||||
Use the noexcept keyword with tact, not by default. Most of the project
|
||||
propagates exceptions. Functions that handle their errors and are expected to
|
||||
return (i.e since they catch `std::exception`), still throw special exceptions
|
||||
like `ircd::ctx::terminated`. If the `catch(...)` and `noexcept` features are
|
||||
used: developers must cooperate by handling ctx interruptions and propagating
|
||||
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.
|
||||
The `noexcept` specifier is employed to mark non-inline functions which don't
|
||||
throw; we elide `noexcept` for inline functions which don't throw unless there
|
||||
is an explicit reason for it. The former provides valuable information to the
|
||||
compiler affecting optimization around calls where the compiler can't see
|
||||
the callee's implementation to deduce it doesn't throw.
|
||||
|
||||
|
||||
#### Indications of yielding and IO's
|
||||
|
||||
There is a section on how yielding and IO can occur far up the stack from a
|
||||
benign-looking callsite in ctx/README. We try to make comments to indicate
|
||||
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.
|
||||
Most of the project propagates exceptions. Functions that handle their errors
|
||||
and are expected to return (i.e since they catch `std::exception`), still throw
|
||||
special exceptions like `ircd::ctx::terminated`. If the `catch(...)` and
|
||||
`noexcept` features are used: developers must cooperate by handling ctx
|
||||
interruptions and propagating terminations.
|
||||
|
||||
|
||||
#### Nothing ticks
|
||||
|
|
Loading…
Reference in a new issue