MirrorHub/construct
0
0
Fork 0
mirror of https://github.com/matrix-construct/construct synced 2024-11-16 06:51:08 +01:00
Code Issues Releases Wiki Activity

Update STYLE.

Browse source
This commit is contained in:
Jason Volk 2018-01-18 16:11:16 -08:00
parent 31fd9346f6
commit c15d13ffdc
1 changed files with 36 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
doc/STYLE.md
View file

@ -110,12 +110,12 @@ This means when a variable, or member (a **resource**) first comes into scope,
i.e. it is declared or accessible (**acquired**), it must be **initialized** i.e. it is declared or accessible (**acquired**), it must be **initialized**
to a completely consistent state at that point. to a completely consistent state at that point.
* Window shade analogy:
> >
> Imagine pulling down a window shade to hide the sun. As you pull down, the canvas > Imagine pulling down a window shade to hide the sun. As you pull down, the canvas
> unrolls from its spool at the top. Your goal is to hook the shade on to the nail > unrolls from its spool at the top. Your goal is to hook the shade on to the nail
> at the bottom of the window: that is a commitment. If you slip and let go, the > at the bottom of the window: that is reaching the return statement. If you slip
> shade will roll back up into the spool at the top: that is an exception. > and let go, the shade will roll back up into the spool at the top: that is an
> exception.
> >
> What you can't do is prepare work on the way down which needs _any_ further pulling > What you can't do is prepare work on the way down which needs _any_ further pulling
> to be in a consistent state and not leak. You might slip and let go at any time for > to be in a consistent state and not leak. You might slip and let go at any time for
@ -123,9 +123,9 @@ to a completely consistent state at that point.
> requiring more pulling. > requiring more pulling.
> >
> Indeed slipping and letting go is an accident -- but the point is that *accidents > Indeed slipping and letting go is an accident -- but the point is that *accidents
> happen*. They're not always your fault, and many times are outside of your control. > happen*. They're not always your fault, and many times are in other parts of the
> This is a good approach for robust and durable code over long-lived large-scale > code which are outside of your control. This is a good approach for robust and
> projects. > durable code over long-lived large-scale projects.
> >
@ -226,9 +226,29 @@ the ability to assign, move, and reuse the object because references cannot be
reseated; then the "~~big three~~" "big five" custom constructors have to be reseated; then the "~~big three~~" "big five" custom constructors have to be
created and maintained, and it becomes an unnecessary mess. created and maintained, and it becomes an unnecessary mess.
#### Comments #### Comments
##### Documentation will be pedantic, windy and even patronizing
This is considered a huge anti-pattern in most other contexts where comments
and documentation are minimal, read by experts, end up being misleading, tend
to diverge from their associated code after maintenance, etc. This project is
an exception. Consider two things:
1. This is a free and open source public internet project. The goal here
is to make it easy for many-eyeballs to understand everything. Then,
many-eyeballs can help fix comments which become misleading.
2. Most free and open source public internet projects are written in C
because C++ is complicated with a steep learning curve. It is believed
C++ reduces the amount of many-eyeballs. A huge number of contributions
to these projects come from people with limited experience working on
their "first project."
Therefor, writers of documentation will consider a reader which has
encountered IRCd as their first project*, specifically in C++. Patronizing
explanations of common/standard C++ patterns and intricacies can be made.
* `/* */` Multi-line comments are not normally used. We reserve this for * `/* */` Multi-line comments are not normally used. We reserve this for
debugging and temporary multi-line grey-outs. The goal for rarely using this debugging and temporary multi-line grey-outs. The goal for rarely using this
is to not impede anybody attempting to refactor or grey-out a large swath of is to not impede anybody attempting to refactor or grey-out a large swath of
@ -251,7 +271,7 @@ C++14 std::make_unique() and std::make_shared().
* We allow some C-style arrays, especially on the stack, even C99 dynamic sized ones; * We allow some C-style arrays, especially on the stack, even C99 dynamic sized ones;
there's no problem here, just be responsible. there's no problem here, just be responsible.
* std::array is preferred for object members; also just generally preferred. * `alloca()` will not be used.
* C format strings are still acceptable. This is an IRC project, with heavy * C format strings are still acceptable. This is an IRC project, with heavy
use of strings and complex formats and all the stringencies. We even have use of strings and complex formats and all the stringencies. We even have
@ -281,6 +301,14 @@ 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.
### Conventions ### Conventions
These are things you should know when mulling over the code as a whole. These are things you should know when mulling over the code as a whole.
@ -311,22 +339,3 @@ to move *back* to `strn*` style but it's not prudent at this time.
terminated output into the buffer. These functions usually return a size_t terminated output into the buffer. These functions usually return a size_t
which count characters printed *not including null*. They may return a 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).
#### assert() volatility
- Consider any code inside a runtime `assert()` statement to **entirely**
disappear in optimized builds. Some implementations of `assert()` may only
elide the boolean check and thus preserve the inner statement and the effects
of its execution. We do not rely on this. Do not use `assert()` to check
return values of statements that need to be executed in optimized builds.
- Furthermore, consider the **assert statement itself to be physically erased**
from the code during optimized builds. Thus the following is a big mistake:
```
if(foo)
assert(!bar);
if(baz)
bam();
```