move modules from kebab-case to snake_case #14439
Conversation
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @ehuss (or someone else) some time within the next two weeks. Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (
|
rustbot
added
A-documenting-cargo-itself
src/doc/src/guide/project-layout.md
Outdated
| │ ├── named_executable.rs | ||
| │ ├── another_executable.rs | ||
| │ └── multi_file_executable/ |
There was a problem hiding this comment.
I believe this would have end-user affects, making the default binary names use _ when the status quo is for binaries to use -.
As these are not just mod names but build target names, i would be inclined to leave all of these as -
|
Thanks for the PR! I think there may be some confusion, as these filenames do not represent crate names, they are target names. Considering that there isn't a standard for how those should be named, I'm disinclined to change these here. Indeed, cargo's own repository makes use of hyphen in most places. |
Should we call that out in this page then? I am happy with |
|
I have tried to add some clarity by explicitly stating my current understanding here. What do you think? One thing I debated was if using a single word for targets should be recommended but that does not feel right. |
| @@ -48,6 +48,8 @@ files, place a `main.rs` file along with the extra [*modules*][def-module] | |||
| within a subdirectory of the `src/bin`, `examples`, `benches`, or `tests` | |||
| directory. The name of the executable will be the directory name. | |||
|
|
|||
| Binaries, examples, benches and integration tests follow `kebab-case` naming style. Modules within those targets are `snake_case` following the [Rust standard](https://rust-lang.github.io/rfcs/0430-finalizing-naming-conventions.html). | |||
There was a problem hiding this comment.
This is likely best left to a style guide, with us finding an appropriate place to link out to it.
There was a problem hiding this comment.
Is there a style guide that makes sense to use?
There was a problem hiding this comment.
The way I see it, right now no one in the rust ecosystem directly says that build targets are kebab-case. This document is the closest but it is not clear.
|
Are cargo targets a cargo concept? If so can we define the naming convention somewhere here in the cargo docs that says those targets should be |
There was a problem hiding this comment.
In reply to #14439 (comment):
Are cargo targets a cargo concept?
Yes. See https://doc.rust-lang.org/nightly/cargo/reference/cargo-targets.html.
If so can we define the naming convention somewhere here in the cargo docs that says those targets should be
kebab-case?
What's the benefit of it?
There was a problem hiding this comment.
The thing is without a codified standard its hard to enforce. So people will start drifting and you will end up with multiple groups doing different things. If it becomes part of the docs then its easier to PR lints into Clippy in order to enable automatic enforcement for projects and makes the ecosystem easier and more coherent.
There was a problem hiding this comment.
Thank you for explaining that :)
There was a problem hiding this comment.
If it becomes part of the docs then its easier to PR lints into Clippy in order to enable automatic enforcement for projects and makes the ecosystem easier and more coherent.
I suspect this lint should live in cargo, not clippy.
There was a problem hiding this comment.
That's fair. However we still need to spell out the rule in some docs first and I think this is the place for it.
There was a problem hiding this comment.
I disagree that this is the place for it.
Also, even better than documenting this is to lint for it. If we have specific naming recommendations, we can use #12235 (unstable implementation is in place) to lint for naming like rustc does for functions, structs, etc.
There was a problem hiding this comment.
Also, even better than documenting this is to lint for it.
100% agree. However you end up in a chicken and egg problem. If I propose a semantic lint like this with no docs to support it, then I will end up with a really hard time getting it merged. So its just a first step here to remove an ambiguous situation.
There was a problem hiding this comment.
So where specifically should I try to put this?
There was a problem hiding this comment.
What does this PR try to resolve?
It is currently unclear reading the docs how files should be named. RFC 430 is clear on crates and module names,
kebab-caseis never mentioned and while there are historical considerations, we should guide new development towardssnake_case. We should align the documented defaults to that RFC.How should we test and review this PR?
Review the docs and determine if we view value in the change.