Naming of Files and Distribution of Code

Hi,

I come from a backgound of C++, C#, Java and now Typescript and wanting to organize my files so people can find stuff when they look at my work. For Rust I am trying to find a good site or video (I struggle with reading) which outlines the right way to approach this.

In my typescript project I try and break projects down by function and then technical approach (these are not real names :slight_smile: )

E.g.

Pages
   pageOne
       pageOneNotShareComponent1
       pageOneNotShareComponent2
   pageTwo
Components
   Component1
   Component2
   Component3
Mappers
   mapper1.ts
   mapper2.ts
   mapper3.ts
Reducers
   reducer1.ts
Types
  type1.ts
Services
  service1.ts
  service2.ts
  service3.ts

Sorry to type so much but here is my Rust example. So for rust I am OK with structs, one struct per file (could be wrong of course), for large structs I break into mods and put the trait implementations in their file.

But...
functions struggling with if not on a struct
Enum one per file?

I know there is no one solutions and teams have different approaches but are there reference sites that have down this well (at least for some people) which I could look at.

The example that stopped me in my tracks was a chat example with JSON being used so there is a

pub async fn send_json<O, P>(leaving: &mut O, packet: &P) -> ChatResult<()>
pub fn recv_json<I, T>(incoming: I) -> impl Stream<Item = ChatResult<T>>

These live in utils.rs but this is really hard to find without vscode and f12. I am used to being able to look at the name know. I would be tempted to use struct like a class and name this something reasonable.

Thanks, hope this does not sound too trivial.

Create modules organized around ideas, not necessarily types. Those sound like they belong in a module called json. Maybe they can be called json::send() and json::recv(), even.

Of course, you probably actually use JSON for more things than this, and even if you don't, it doesn't convey much. So, come up with a name for the specific protocol these functions implement two sides of, and name the module after that.

3 Likes

Thanks for replying but I am after really something a bit more of a higher level. I provided the example, to demonstrate.

Looking for a reference project or a youtube with how to make a reasonable sized project project (Slighty bigger than a chat with a client/server and shared library).

Ideally it would be useful for someone who has never seen my app to understand the high-level and be able to navigate to the low-level. Again for another example you might have

- Router
  - Controller
    - Controller1
    - Controller2
  - Service
    - Service1
    - Service2
  - DoA
Types
  - Requests
  - Responses

This shows how you might approach a nodejs project. Just looking for an approach with Rust, that Other people would recognize instantly.

Make sense?

There is no one layout that is even suitable, let alone recommended, for “reasonable sized projects”, because there are all sorts of projects. But I take it from your example that what you are thinking of is not really any “project” but “a web application server”. That's far more specific (than the set of all medium-sized things that could be written in Rust), and I'm afraid I don't know of good examples of a web application server in Rust — it's just not a sort of program I currently work with a lot.

But still: the modules that suit your code will depend on the goals of your application, and the framework/libraries you are using. If your modules have an extremely regular structure, that's a sign that you might be writing code that ought to be data.

2 Likes

Thanks again for answering.

Sorry clearly not phrasing the problem think I am trying to solved right.

Here is
web examples
react approach here
nodeJS [here](https://blog.logrocket.com/node-js-project-architecture-best-
practices/)
golang here

And some videos
typescript here
nodejs here

I do not necessarily advocate these as I have only skimmed to demonstrate the idea of what I am after. I have been writing code for 40 years so hopefully (or maybe not) I have a bit of clue for the basics.

I have banned myself from C++ and set a goal to be adequate with Rust in 2024

For Rust I have found videos for workspace, and libraries and I understand how to do these but I am after an approach, pattern or best practice. Often there are Github you can go to to cadge what to do.

My hope on this forum was some who has been doing rust for a long time had resources I could look at and be happy I am approaching my code layout in a fashion others would understand.

In terms of project structuring... there's nothing special about Rust other than workspaces.

  • Have you worked with other programming languages? Great! Organize your files as you have done in the past in those programming languages.
  • Do you mostly program solo? Then organize the files in a way that helps you navigate throughout your code more easily.
  • Have you worked in teams with similar projects? Then you should know how such projects should be organized.
1 Like

Personally I don't bother. Maybe my projects are not big enough...

All my source files go under src. Apart from when creating multiple binaries then we have /src/bin
Files are likely named after significant features. Often the same or similar name to the struct or such that implements that feature. Otherwise named after their functionality. I try to avoid names like utils that tend to accumulate random and unrelated things.

Finding things is he job of grep quite often.

The question is why add the complexity of a bunch of subdirectories? For example in the the OP there are a lot of files whose names are prefixed (almost) with the name of the directory they are in: Components/Component1. I consider that Components redundant as it is repeated in the files names themselves.

1 Like

One file per type is not common practice in Rust. As @kpreid wrote, you can put standalone functions in modules that contain other related stuff, like a json module for JSON related functionality. You can also put related types and their trait implementations, impl blocks, constants etc. in that same module with the related standalone functions.

I'm not aware of such a resource existing. If you have a specific kind of project in mind you can look at similar Rust projects for inspiration, but there's no language-wide standard. Even the TS/Node/React layouts you linked are for very specific kinds of projects only (website/server), and the Go layout doesn't say anything about how to structure your code.

From what I've seen, BurntSushi's repositories such as https://github.com/BurntSushi/ripgrep are a good example of what I'd consider idiomatically structured code. A workspace with a crates directory is a pattern I like a lot, and for example https://github.com/BurntSushi/ripgrep/blob/master/crates/core/search.rs is an example of a file containing several types and standalone functions related to a single concept.

4 Likes

Worked on large and small project,IBM, Unisys. Always found organization and naming key. 2k of files, you probaby want an approach. With C++ kinda easy as you only have .h,.cc and .inl. Enjoyed doing frontend and yes I wouldn't name something Component1.ts.

More than familar with awk and grep but again not really the best approach.

I think from this thread, pretty clear that no approach is going to be frawned on.

1 Like

By the time you have written that much code, you'll probably have developed your own sense for what works for the kind of code you write.

Another angle that I didn't think to mention before: if you're developing a library, then its public modules should be organized in a way which makes sense for using it — modules containing related items that are often used together, or should be understood together when reading the documentation. Then, since Rust encourages the file structure to follow the module hierarchy, that determines your files. Non-library crates and private modules don't have this “what does this make the API look like” factor, but any sufficiently large crate will have parts of it that are library-like and you can think about how to design it from that perspective.

3 Likes

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.