rust-lang / rust-lang/reference
Revise advice about which naming convention to use for modules
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1.6k
- Forks
- 607
- PR merge metrics
- PR metrics pending
Description
It seems people are interpreting this line in the Modules page of the reference...
It is encouraged to use the new naming convention as it is more consistent, and avoids having many files named
mod.rswithin a project.
...to mean that the mod.rs approach to laying out a project on disk is deprecated, which is at odds with this line from RFC 2126.
The use of
mod.rscontinues to be allowed without any deprecation. It is expected that tooling like Clippy will push for at least style consistency within a project, and perhaps eventually across the ecosystem.
It also refers to the new convention as "more consistent" when, without going into the RFC an enumerating the bullet points, moving away from having all the .rs files within a single folder feels differently consistent, not more so.
Please consider adjusting the phrasing to make it more clear that this is not an official statement of policy but merely a piece of advice.
Perhaps something along the lines of this:
If you are uncertain which convention to follow, we recommend using the new naming convention as it simplifies the addition of new submodules as your project grows and makes it easier for your editor to display unambiguous names for open files.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Modules page in the Rust Reference and review the cited wording alongside RFC 2126. Revise the advice so it is clearly a recommendation rather than a deprecation or official policy statement, while preserving the distinction between the naming conventions.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100