From 7e56bf250bff3dae457bbca4ef7b3322048a7940 Mon Sep 17 00:00:00 2001 From: Ruihang Xia Date: Wed, 17 Apr 2024 19:28:02 +0800 Subject: [PATCH] docs: add style guide (#3730) * docs: add style guide Signed-off-by: Ruihang Xia * add comments section Signed-off-by: Ruihang Xia * add comment order Signed-off-by: Ruihang Xia * about error handling Signed-off-by: Ruihang Xia * about error logging Signed-off-by: Ruihang Xia --------- Signed-off-by: Ruihang Xia --- CONTRIBUTING.md | 2 +- docs/style-guide.md | 46 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 1 deletion(-) create mode 100644 docs/style-guide.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dcbef7b53082..94bfb60ac35c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,7 +50,7 @@ GreptimeDB uses the [Apache 2.0 license](https://github.com/GreptimeTeam/greptim - To ensure that community is free and confident in its ability to use your contributions, please sign the Contributor License Agreement (CLA) which will be incorporated in the pull request process. - Make sure all files have proper license header (running `docker run --rm -v $(pwd):/github/workspace ghcr.io/korandoru/hawkeye-native:v3 format` from the project root). -- Make sure all your codes are formatted and follow the [coding style](https://pingcap.github.io/style-guide/rust/). +- Make sure all your codes are formatted and follow the [coding style](https://pingcap.github.io/style-guide/rust/) and [style guide](http://github.com/greptimeTeam/docs/style-guide.md). - Make sure all unit tests are passed (using `cargo test --workspace` or [nextest](https://nexte.st/index.html) `cargo nextest run`). - Make sure all clippy warnings are fixed (you can check it locally by running `cargo clippy --workspace --all-targets -- -D warnings`). diff --git a/docs/style-guide.md b/docs/style-guide.md new file mode 100644 index 000000000000..901bd56efaec --- /dev/null +++ b/docs/style-guide.md @@ -0,0 +1,46 @@ +# GreptimeDB Style Guide + +This style guide is intended to help contributors to GreptimeDB write code that is consistent with the rest of the codebase. It is a living document and will be updated as the codebase evolves. + +It's mainly an complement to the [Rust Style Guide](https://pingcap.github.io/style-guide/rust/). + +## Table of Contents + +- Formatting +- Modules +- Comments + +## Formatting + +- Place all `mod` declaration before any `use`. +- Use `unimplemented!()` instead of `todo!()` for things that aren't likely to be implemented. +- Add an empty line before and after declaration blocks. +- Place comment before attributes (`#[]`) and derive (`#[derive]`). + +## Modules + +- Use the file with same name instead of `mod.rs` to define a module. E.g.: + +``` +. +├── cache +│ ├── cache_size.rs +│ └── write_cache.rs +└── cache.rs +``` + +## Comments + +- Add comments for public functions and structs. +- Prefer document comment (`///`) over normal comment (`//`) for structs, fields, functions etc. +- Add link (`[]`) to struct, method, or any other reference. And make sure that link works. + +## Error handling + +- Define a custom error type for the module if needed. +- Prefer `with_context()` over `context()` when allocation is needed to construct an error. +- Use `error!()` or `warn!()` macros in the `common_telemetry` crate to log errors. E.g.: + +```rust +error!(e; "Failed to do something"); +```