docs: Add code style guide #888
No reviewers
Labels
No labels
Bug
Cherry-picking
Database
Dependencies
Difficulty
Easy
Difficulty
Hard
Difficulty
Medium
Documentation
Enhancement
Good first issue
Help wanted
Inherited
Matrix/Administration
Matrix/Appservices
Matrix/Auth
Matrix/Client
Matrix/Core
Matrix/Federation
Matrix/MSC
Matrix/Media
Meta
Meta/Packaging
Priority
Blocking
Priority
High
Priority
Low
Security
Status
Confirmed
Status
Duplicate
Status
Invalid
Status
Needs Investigation
Wont fix
old/ci/cd
old/rust
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference: continuwuation/continuwuity#888
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "jade/docs-updates-20250701"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Expanding on some stuff noted in the development room.
Also improves deployment documentation.
@ -123,4 +106,0 @@
[do not replicate the name in your functions or
variables](https://developers.google.com/style/inclusive-documentation#write-around).
In addition to language, write and code with the user experience in mind. This
I (personally) think this entire paragraph should be included verbatim in the moved part.
@ -36,6 +26,10 @@ You can run these checks locally by installing [prefligit](https://github.com/j1
```bash
# Requires UV:
Linking to https://docs.astral.sh/uv/getting-started/installation/ too is probably good to reassure paranoid viewers that they aren't expected to just run some random internet script
@ -48,6 +42,8 @@ prefligit --all-files
Alternatively, you can use [pre-commit](https://pre-commit.com/):
```bash
# Requires python
Which python? (3.12 or above? etc)
It doesn't say, although 3 would be implied. I don't think it particularly matters, people are gonna install something reasonably up-to-date
@ -0,0 +118,4 @@
Use appropriate log levels:
- `error!`: Unrecoverable errors that affect functionality
- `warn!`: Potentially problematic situations that don't stop execution
Something more like
"situations that don't stop execution" feels more oriented to applications rather than server daemons - warnings within an environment like ours are totally natural and even expected, this phrasing makes them feel more worrying than they are.
This is in the context of a single request, or server startup. If the request is aborted unexpectedly, error and return. If the request can continue running/executing, warn. Executing does still make sense here IMO.
might be recoverable doesn't always make sense, although the latter bit does a bit
@ -0,0 +184,4 @@
Use the `WithLock` trait from `continuwuity-core::utils::with_lock`:
```rs
use continuwuity_core::utils::with_lock::WithLock;
we haven't renamed the packages yet
Me being silly
@ -0,0 +205,4 @@
For async contexts, use the async variant:
```rs
use continuwuity_core::utils::with_lock::WithLockAsync;
see prior
@ -0,0 +318,4 @@
The following types of language are explicitly forbidden in all code, comments, documentation, and commit messages:
**Ableist language:** Avoid terms like "sanity check", "crazy", "insane", "cripple", or "blind to". Use alternatives like "validation", "unexpected", "disable", or "unaware of".
This is a really difficult thing to enforce, because different cultures consider albeism differently, and there isn't really a concrete definition. If we're going to require this, it should be defined in a more general/broad sense, rather than explicitly listing examples and alternatives.
FWIW, this is pretty much copied from the linked guidelines. The best you can really do is provide a baseline set of examples and then leave it up to discretion. Some words are obvious, some words require more cultural context/history/etymology to flag.
@ -0,0 +328,4 @@
Use diverse examples in documentation that avoid culturally-specific references, assumptions about user demographics, or unnecessarily gendered language. Design with accessibility and inclusivity in mind by providing clear error messages and considering diverse user needs.
This software is intended to be used by everyone regardless of background, identity, or ability. Write code and documentation that reflects this commitment to inclusivity.
See above comment in the removed section of CONTRIBUTING.md
823c73f480
toad4651167a
22e3a15dc0
to0a8c13ffd2