From 535e84357c00fed2e5ebfa21acd0e4e621bbe44a Mon Sep 17 00:00:00 2001 From: Jason Volk Date: Wed, 8 Jul 2020 10:12:41 -0700 Subject: [PATCH] Various updates; remove unnecessary sections. --- STYLE.md | 64 ++++++++++---------------------------------------------- 1 file changed, 11 insertions(+), 53 deletions(-) diff --git a/STYLE.md b/STYLE.md index e0e9b2a..602e672 100644 --- a/STYLE.md +++ b/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