Rough code style guidelines

[bobbinth]

Here is an initial list of coding style guidelines we use. Probably some things are missing but we can add on to this list as the time goes on. Also, these are just general rules. It is OK to deviate from these when this improves code readability. And obviously, happy to discuss any of these.

1. Try not to go over 100 characters in a line.
2. Try not to have files with over 500 - 600 lines.
3. Unit tests should be in the sub-module of the module they are testing. We put unit tests into a tests module.
4. If a file is not too large, the tests module can be in the same file as its parent. Otherwise, we move tests into a separate file under the same module.
5. Main components of a module should be at the top of the file. Helper structs/functions and tests should be at the end of the file.
6. Use section separators between different logical sections of a file (e.g., different structs, main vs. helper functions etc.). For section separators we usually use equal signs (=).
7. Within structs, group methods by their logical functions (e.g., constructors, accessors, state mutators, helper methods etc.). We use dashes (-) for section separators within structs.
8. When importing modules, group imports by crate.
9. If multiple submodules use the same import, move the import into the parent module and import from super.
10. When exporting components, try to avoid exporting both the component and its parent module.
11. Try to minimize the surface of public interfaces as much as possible (i.e., whatever doesn't need to be public, should stay private).
12. Try to use named constants and type aliases in favor of inline constants and complicated inline types. Put constants and type declarations at the top of the file (right after imports).
13. Methods which perform simple data access do not need to be prefixed. For example, if id is a property of Foo, use foo.id() rather than foo.get_id().
14. Methods which do perform work, should have a prefix (e.g., get_, build_ etc.). For example, foo.get_hash() if hash is being computed inside get_hash().

[polydez]

Suggestion to 14. For methods which perform work, it's better not to use get_ prefix since it might be misleading and considered as getter. IMO, build_ is fine, as well as compute_ and calculate_ or just calc_.

[bobbinth]

I've used get_ when the work is pretty minimal (but still more than just returning a field) and build_, compute_ etc. when the works is substantial.

Also, I'd probably use compute_ over calculate_ - a bit shorter and means pretty much the same thing.

[hackaugusto]

@bobbinth should we use this discussion to figure out the coding guidelines for all repos?

Here are some of the previous discussions that I know about:

• Contributing guideline miden-vm/#337
• Miden assembly style guidelines miden-vm/#698
• Format for the use statements on rust code #1043
• discord: tooling
• Write tool to format Cargo.toml miden-vm/#1278
• discord: branch model

@bitwalker @plafer @greenhat @polydez I suppose you guys will want to share your POV too.

[bobbinth]

Yep - I think this is the right place. Overall, I think the ideal outcome would be to come up with:

1. Updated Contributing.md which would upload to all repos.
2. Update issue/PR templates for all repos.
3. Same formatting (rustfmt and clippy) for all repos.
4. Same methodology for running tasks in all repos (i.e., cargo vs. make vs. cargo make).
5. Same approach to making releases across all repos (e.g., maybe using something like cargo release).

I think on 2 and 3 above we are pretty close. The other ones could have separate discussion threads in here.