# Style Guide(Draft)

## Base(or basic?) guides

When it comes down to resolving conflicts, we always refer to these base style guides:

- [Rust Style Guidelines 1.0.0](https://doc.rust-lang.org/1.0.0/style/README.html)
- [The Nightly Rust Style Guide](https://doc.rust-lang.org/nightly/style-guide/index.html)
- [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) **[TODO: not sure]**
- [Google's Code Review Developer Guide](https://google.github.io/eng-practices/review/)

## A few principles to start with

The star(★)s reflect the effort we should put into the practice of a singular principle or a group of principles.

### Rust

1. Follow the official/orthodox/canonical [Naming Conventions](https://doc.rust-lang.org/1.0.0/style/style/naming/README.html) ★★★★★
2. Follow the official [comment style](https://doc.rust-lang.org/1.0.0/style/style/comments.html) ★★★
3. Macros ★★★★★
- Macros must be thoroughly documented
- Only used in situations where functions fail to provide the desired solution
4. Avoid unsafe code ★★★
5. Traits
- Prefer not to write `ink!` traits :( ★

### Javascript

- Prefer Typescript ★★★★★
- **[TODO: other things]**

### General Coding style

- Comments must have a space after forward slash(`/`), slash/asterisk combination(`/*`) or hash mark(`#`) ★★★★★
- Prefer few lines of code, the maximum line count of a function should be $2^5 = 32$ or $2^4 = 16$ ★★
- Do not overdesign or overengineering ★★★★★
- Do the simplest thing that could possibly work, do not purchase fancy concepts, dark magic, and advanced language features

### Code Review

- Comments should provide positive feedbacks, point out logic defects, and contain strong reasoning with references to design documents, style guides, code or test results. ★★★★★
- Do not judge people's code style if their code has passed the validation of linting and formatting tools in CI, if you have to do that, always refer to the base guides. ★★★★★
- Ask at least two people to review your code, one of them should understand the project, another one can be anyone else, regardless of his/her job title, level, or when he/she joined the company. ★★★★
- Squash all commits into one commit when it comes to PR merging. ★★★
- A PR should not last longer than 2 days. ★★★

### Documents

- Architecture designs or proposals should follow a certain style **[TODO: find one]** ★
- [RFC 7322, RFC Style Guide](https://www.rfc-editor.org/rfc/rfc7322)
- [0000-template.md](https://github.com/rust-lang/rfcs/blob/master/0000-template.md)
- [Project architecture document template](https://github.com/bflorat/architecture-document-template)

## Tools that help follow a style

- [ ] CI:
- [x] cargo clippy
- [x] cargo rustfmt
- [ ] other things?
- [ ] Pull request templates

## References

- [How to write Rust code in the kernel](https://www.kernel.org/doc/html/latest/rust/coding-guidelines.html)
- [Rust Style Guide](https://github.com/rust-dev-tools/fmt-rfcs/blob/master/guide/guide.md)
- [Unsafe Code Guidelines](https://github.com/rust-lang/unsafe-code-guidelines/)
- [Configuring rustfmt](https://github.com/rust-lang/rustfmt#configuring-rustfmt)
- [When to use and not use Rust macros](https://subscription.packtpub.com/book/application-development/9781838828103/9/ch09lvl1sec76/when-to-use-and-not-use-rust-macros)
- [What are the pros and cons of using macros in rust?](https://www.reddit.com/r/rust/comments/taxfe3/what_are_the_pros_and_cons_of_using_macros_in_rust/)
- [The 80/24 rule](https://blog.ploeh.dk/2019/11/04/the-80-24-rule/)
- [What is the ideal length of a method for you?](https://softwareengineering.stackexchange.com/questions/133404/what-is-the-ideal-length-of-a-method-for-you)
- ["You aren't gonna need it" (YAGNI) is a principle which arose from extreme programming (XP) that states a programmer should not add functionality until deemed necessary.](https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it)
- [PR/Code Review Best Practices](https://dev.to/nirajkvinit/pr-code-review-best-practices-5363)
- [Code Smells](https://blog.codinghorror.com/code-smells/)
- [Substrate workflows]([https://github.com/paritytech/substrate/tree/js/uniques-v2-main-branch/.github](https://github.com/paritytech/substrate/tree/js/uniques-v2-main-branch/.github))
- [ComposableFi/composable workflows]( [https://github.com/ComposableFi/composable/tree/main/.github](https://github.com/ComposableFi/composable/tree/main/.github))