MirrorHub/construct
0
0
Fork 0
mirror of https://github.com/matrix-construct/construct synced 2024-06-01 01:28:54 +02:00
Code Issues Releases Wiki Activity

Update README; Update STYLE.

Browse source
This commit is contained in:
Jason Volk 2018-02-11 11:51:20 -08:00
parent b94d0b8ce6
commit db22d22eab
2 changed files with 49 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -17,7 +17,7 @@ real-time communication for free and open source software: a *federation of netw
**IRCd has been rewritten to implement the [Federation](https://matrix.org/docs/spec/)**.
This is the opportunity to take back control of your communication and relegate the
opaque cloud services to being just another provider to the federation.
opaque cloud siloes to being just another provider to the federation.
Though not syntactically backwards-compatible with the legacy IRC protocol, it is easily
translated as a superset. Similar to the legacy IRC protocol's origins, it wisely leverages
technologies in vogue for its day to aid the virility of implementations. A vibrant and

83
doc/STYLE.md
View file

@ -228,44 +228,10 @@ 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
created and maintained, and it becomes an unnecessary mess.
#### 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
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
code.
* `//` Primary developer comment; used even on multiple lines.
* `///` Documentation comment; the same style as the single line comment; the
documentation is applied to code that follows the comment block.
* `///<` Documentation comment; this documents code preceding the comment.
#### Miscellaneous
* Prefer "locality" rather than "centrality." In other words, we keep things
in as local of a scope or file as possible to where it is used.
@ -313,6 +279,53 @@ of its execution: this is not standard; we do not rely on this. Do not use
optimized builds.
#### Comments
* `/* */` Multi-line comments are not normally used. We reserve this for
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
code.
* `//` Primary developer comment; used even on multiple lines.
* `///` Documentation comment; the same style as the single line comment; the
documentation is applied to code that follows the comment block.
* `///<` Documentation comment; this documents code preceding the comment.
##### 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.
### Art & Tableaux
* Tab style is **tabs before spaces**. Tabs set an indentation level and
then spaces format things *at that level*. This is one of the hardest styles
to get right and then enforce, but it looks the best for everyone. The point
here is that the tab-width becomes a personal setting -- nobody has to argue
whether it's worth 2 or 4 or 8 spaces... Remember, tabs are never used to
align things that would fall out of alignment if the tab-width changed.
### Conventions
These are things you should know when mulling over the code as a whole.