Revise advice about which naming convention to use for modules

Open Beginner friendly
#1,215 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Stale
Tech stack
rust
Domain
documentation

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.

Description

Language Cleanup

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.rs within 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.rs continues 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.

Dominant language
Rust
Stars
1.6k
Forks
607
Avg merge
1d 1h
Merged PRs (30d)
12

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from rust-lang/reference

All issues in rust-lang/reference

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.