Document Code Review Principles #3596
Conversation
| - Are `lib.rs` or `mod.rs` files added? In general these should only be used to | ||
| reference other modules and setup exports. Actual OS logic should be in | ||
| descriptively named files. |
There was a problem hiding this comment.
I know that we've been generally following this rule, but Rust's module system sometimes makes it very awkward to require mod.rs at some::path::in::the::module::hierarchy, but then require an extra ::spurious_module_path at the end, just because we add another descriptively named file. In many ways we can work around this through reexports, but we also have counterexamples in the repository.
The current text says "in general these should", and that seems like fine language to me, if it's indeed not actually meant to be a hard rule.
There was a problem hiding this comment.
We have a legacy dating back to the beginnings of tock of using lib.rs in arch crates which I guess is ok, hence my hedging. (Although, actually looking at the commits my excuse isn't really valid, we had a different file and moved it to lib.rs :( 2c1d620)
That being said, for me it is a rule: either you have little code/modularity and do not need a crate/folder, or you have enough code/modularity to warrant a crate/folder and the structure should plan for mode code to be added in the future (i.e. do not use the mod/lib file).
Add fixes and clarifications. Co-authored-by: Leon Schuermann <[email protected]> Co-authored-by: Branden Ghena <[email protected]>
Updates from PR. Co-authored-by: Pat Pannuto <[email protected]>
|
Merge this? |
Pull Request Overview
This is part of #3563.
This is an attempt to write down what PR reviewers are/should be looking for when reviewing PRs. Hopefully this helps both reviewers and submitters.
Testing Strategy
n/a
TODO or Help Wanted
Please add commits with additional information.
Documentation Updated
/docs, or no updates are required.Formatting
make prepush.