Module naming conventions

Hi @joeerl! In Elixir, we usually follow a direct mapping from module name to file name. So a file named MyApp.Sensors.Supervisor should be put in lib/my_app/sensors/supervisor.ex. So maybe you want to report this to the scenic project and get their $.02 on the topic.

Note it is just a convention though, Elixir does not care about the filename as long as it ends with .ex.

Hi @josevalin - I’m not sure about this convention. Breaking the convention will confuse people.

Suppose you have a single module defining say JoesApp.lib.misc and put it in a file called crypto/utilities/rsa.ex this will confuse everybody and is a violation of the principle of least astonishment. If you have hundreds of thousands of modules then you’ll have to build an index to find a particular module.

I would have liked a stronger convention - something like if there is no good counter-reason the file and module names should be identical. And if they are different the reason should be documented.

(actually I’d really like no readable file names at all - all file names should be SHA’s of the content and in a global content addressable store - but we’re not there yet

A counter case would be when the file names is (say) the SHA1 of the content or a UUID (I have used both conventions) - here it would be obvious that the file name and module name differ.

Failing a stronger convention, a warning “Gratuitous module/file name used ..” might warn the user that whatever convention they were using might confuse people later.

How do you edit these files? Do you update the filename on each save? This sounds unworkable

Edit with a regular text editor - you could use one file per save or make a write-append file and save diffs. It’s very workable.

GIT essentially does this - but the granularity is “per commit” and not “per file save” - I wrote a wiki years ago that saved all old versions of everything forever - it used diffs and compression - surprisingly saving all old versions forever does not result in huge text files.

Of course, the user should never be aware of the SHAs of the file but see ‘regular’ file names.

Far from being unworkable I think the opposite is true. Write append only files with all old versions have many desirable properties. I hardly dare say that blockchains are “merely” write append stores with all old versions in the chain - the untrusted nature of things like bitcoin make implementations energy inefficient - but in a trusted environment a blockchain reduces to a write append only store with a few crypto certificates throw in for good measure.

Actually journaling files systems are used everywhere, and these are just write append logs.

Storing files in mutable stores which can be overwritten many times has loads of other problems. Long subject - not enough room here to make the case for a content-addressed file store.

Exactly. The convention would ask you to put it inside lib/joes_app/lib/misc.ex. So as long as you follow the convention, not surprises should arise.

Ok, that makes sense. I thought you meant user-visible SHA-based names. I like your approach, yeah. I think version control should be more integrated in the systems we use everyday.

I’ve found that generally in Elixir and Phoenix we don’t pluralise (pluralisation does happen in other frameworks in other languages, like Rails, however it can get messy with edge cases, such as ‘octopus’!).

Naming conventions help a lot in frameworks, so for instance Phoenix will infer the name of certain modules from the name of others. For example it infers the name of the view, AppWeb.UserView, from the controller, AppWeb.UserController. Similarly, the view modules infer their template locations from the module name. So in the example in the Phoenix book, RumblWeb.UserView would look for templates in the rumbl_web/templates/user directory.

If you’re wondering why RumblWeb becomes rumble_web in the directory or why PageController in the module name becomes page_controller in the file name - I guess it’s for readability (and possibly inherited from the Ruby/Rails world - after I imagine quite a bit of discussion around it). There may be other benefits which I am not aware of though.

Once you get used to these conventions, it does make life easier as you don’t have specify them manually (although of course you can should you wish to break these conventions).

With regards to the pluralisation you found in Scenic, maybe @boydm could chime in and let us know his reasoning

@joeerl I think it’s important to understand that not everyone uses the same tools and while putting everything in one directory may work for you it doesn’t for plenty of others. I’ve experienced what you’re describing with Swift (and maybe Obj-C too?). Apple’s XCode editor organizes source files into groupings that look like folders while you’re building things and then modifies a big XML file which saves this change but the files are not organized that way in the file system. Problem is, when looking at the source code via an external tool (maybe you don’t use XCode, or via GitHub or anything else), it’s a giant unmanageable flat list of files for the larger projects that goes on for many screens. They compiler doesn’t recursively traverse directories or something silly like that, it’s quite a hack IMO.

I don’t believe external tools will ever get on board to anything like this and there will always be more and more of them that it will just always become a bigger headache to both advanced users and newcommers alike having to deal with the two different organizational structures.

Elixir usually goes by uppercase camel names for module names and lower snake case for file names. I think this is particularly fitting because the lowercase version is typically accessed via command line (where the standard is typically lowercase for faster typing) and module names make sense as uppercase to denote their importance with respect to the other things around then (variables, ect.).

In general, I’ve been trying to follow the non-plural forms. The only exception has been the Scenic.Primitives and Scenic.Components modules, which are collections of helper files to instantiate those data structures.

I’ll go review the scenic_new project. Came together late in the game…

@joeerl This is a really good question.

When I set up the scenic_new project I took a look at Phoenix and tried to replicate the pluralization there. When you run mix phx.new my_app, it creates a lib/controllers folder, but the modules within have controller in the singular form.

Same goes for views.

When it comes to Scenic, it made sense to follow the Phoenix pattern. An app will have a collection of scenes. So put those in the scenes folder. However, each module defines a single scene, so it would have a name like MyApp.Scene.Whatever.

On further thinking, the folder structure in Phoenix generated apps doesn’t really map to the Module names. In other words,

lib/my_app_web/controllers/page_controller.ex contains MyAppWeb.PageController instead of MyAppWeb.Controller.Page or MyAppWeb.Controllers.Page

To me this breaks the philosophy @josevalim described above.

Personally, I would prefer a module name of MyAppWeb.Controller.Page, which (to me) denotes that it is a single controller. I could go either way if it should live in a folder named controller or controllers, although I have a slight preference for controllers, since that folder contains a collection of individual controllers.

That’s the philosophy I used in the scenic_new generator.

As far as the sensor supervisor goes, the version in master is MyApp.Sensor.Supervisor, which is singular. It lives in the sensors folder, which would be where I would put all the sensors. (I assume a real project would have more than one)

If there is a strong opinion on pluralization of the folders, I can change it, but for now I think it reflects the folder pluralization in Phoenix.