[Pre-RFC] Another subsitution for mod.rs

tools and infrastructure cargo
1

Summary

Currently there are two styles to structure our source code and specify a module's root file. This RFC proposes yet another style, which is similar to the mod.rs style, but avoid the problem of "having multiple mod.rs tabs in the editor".

The file structure will be similar to mod.rs style, except that mod.rs can be renamed as [module name].mod.rs.

Motivation

In RUST2018 the following styles are both legal:

  1. The mod.rs style
    src
├─ my_mod
│  ├─ mod.rs
│  └─ something_else.rs
├─ lib.rs
└─ main.rs
  2. The [module name].rs style
    src
├─ my_mod
│  └─ something_else.rs
├─ lib.rs
├─ main.rs
└─ my_mod.rs

The first style often results in a bunch of mod.rs editor tabs, which is annoying and sometimes error-prone, while the later style may separate a module's implementation into different directories. There is a discussion about this on reddit.

To avoid the duplicate name problem and still have a clean file structure, this RFC propose a third way to specify the module's root file.

Guide-level explanation

The file structure will be similar to mod.rs style, except that mod.rs can be renamed as [module name].mod.rs.

The result will be something like:

src
├─ my_mod
│  ├─ my_mod.mod.rs
│  └─ something_else.rs
├─ lib.rs
└─ main.rs

To prevent ambiguouty, the following practice will result in compile error:

  1. [name].mod.rs where "name" is not the directory's name.
  2. [name].mod.rs and mod.rs both exist.
  3. [name].mod.rs and ../[name].rs both exist.
  4. [name].mod.rs in the root of src/.

Compatibility Issue

Currently, a file named *.mod.rs couldn't be made into a module, so this RFC should work with previous projects well.

2

While I personally am not in love with either of Rust’s current approaches, I think fracturing this even further and adding yet another would be a step backward. I’d like to see more justification and motivation for a proposal like this.

14 Likes
3

Agreed. The new Rust 2018 module system already created a substantial amount of change (for the better, but still change), and introducing a third alternative seems quite unlikely, especially just a change to the mod.rs filename.

If you prefer the mod.rs style, I would suggest changing your editor to display more of the file's path to avoid ambiguity.

I personally prefer the module_name.rs style, both because it produces better results when you don't have nested modules (just a single directory of source files), and because when you do have nested modules it separates submodules from their parent module. I prefer to see a file grouped with its adjacent modules, not with its child modules.

Consider how your proposed directory structure would look with two or three levels of nesting. I prefer main.rs, a.rs, a/b.rs, a/b/c.rs, where you can easily and unambiguously map paths like a, a::b, a::b::c to their filenames. With the mod.rs approach (or variants like your suggested modification), you'd have main.rs, a/mod.rs, a/b/mod.rs, a/b/c.rs. And you'd have to rename a/b.rs to a/b/mod.rs when you introduce the module a::b::c.

2 Likes
4

Yeah, common wisdom is that the quickest way to the top of the mountain is to find the shortest path, but in practice, it is usually just better to just follow in the footsteps of someone who's already been there. Even if it isn't the most efficient path, it is likely to be safer, more well-trodden, and ultimately faster as those reasons tend to be more important than path length.

There needs to be some major flaw with the current options before there's good justification to add yet another option.

the later style may separate a module's implementation into different directories.

This can be avoided by simply not defining anything in other directories. Put only child mod declarations in your mod descriptor file and define everything else within the mod directory.

1 Like