diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md new file mode 100644 index 00000000..4e955e5d --- /dev/null +++ b/STYLE_GUIDE.md @@ -0,0 +1,67 @@ +# Code Style Guide + +Beyond using Cargo format and Clippy, there are some specific code style guidelines laid out in this document for different parts of the project. + +## `core/database` crate + +w.r.t. `model.rs` files + +- All struct definitions must be commented. + ```rust + /// Server + pub struct Server { + /// Name of the server + pub name: String, + ``` +- Struct definitions should not include derives unless necessary (if additional traits such as Hash are required) and instead use `auto_derived!` and `auto_derived_partial!`. + ```rust + auto_derived_partial!( + /// Server + pub struct Server { .. }, + "PartialServer" + ); + ``` +- `auto_derived!` macro accepts multiple entries and should be used as such: + ```rust + auto_derived!( + /// Optional fields on server object + pub enum FieldsServer { .. } + + /// Optional fields on server object + pub enum FieldsRole { .. } + ); + ``` +- If special serialisation conditions are required, such as checking if a boolean is false, use the existing definitions for these functions from the crate root: + ```rust + #[serde(skip_serializing_if = "crate::if_false", default)] + ``` +- `impl` blocks may be defined below the struct definitions and should be ordered in the same order of definition. Methods in the block must follow the same guidelines as traits where-in: methods are ordered in terms of CRUD, there are empty line breaks, and methods are commented. + +w.r.t. `ops` module for models + +- All traits must use a the name format `AbstractPlural` where Plural is the plural form of the collection. e.g. Servers +- Traits defined must follow these guidelines: + + - Methods are ordered in terms of CRUD, create-read-update-delete ordering. + + ```rust + #[async_trait] + pub trait AbstractServerMembers: Sync + Send { + /// Insert a new server member into the database + async fn insert_member(&self, member: &Member) -> Result<()>; + + /// Fetch a server member by their id + async fn fetch_member(&self, server_id: &str, user_id: &str) -> Result; + + /// Update information for a server member + async fn update_member(&self, .. ) -> Result<()>; + + /// Delete a server member by their id + async fn delete_member(&self, id: &MemberCompositeKey) -> Result<()>; + } + ``` + + - There should be an empty line break between each method declaration. + - All methods must have an appropriate comment. + +- When implementing the trait defined in `ops.rs` with each driver, the method declaration style should be the same for ease of searching: same ordering, same comments, same line breaks.