The famous Best Practice Recommendations for Angular App Structure blog post outlines the new recommended angularjs project structure which is now component-oriented, not functionally-oriented, or as named in the initial github issue - "Organized by Feature".
The blogpost suggests that each file inside each module should start with the module name, e.g.:
userlogin/
userlogin.js
userlogin.css
userlogin.html
userlogin-directive.js
userlogin-directive_test.js
userlogin-service.js
userlogin-service_test.js
The question is: what is the point, pros and cons of repeating the module name inside each filename in the module as opposed to having the files named functionally? For example:
userlogin/
userlogin.js
userlogin.css
userlogin.html
controllers.js
directives.js
services.js
The reason I ask is that I'm coming from a Django
world where there is a somewhat similar idea of having projects and apps. Each app usually has it's own models.py
, views.py
, urls.py
, tests.py
. There is no repeating app name inside the script names.
I hope I'm not crossing an opinion-based line and there is a legitimate reason for following the approach.
There is a very good reason and it is for improving a very important aspect for any non-trivial codebase (especially when large teams of developers are involved), namely what we call "overviewability".
"Overviewability" is the ability of the codebase's organzation (folder structure, file naming, meta-objects etc) to provide a quick and informative overview of the implemented software.
The "overviewability's" significance increases exponentially with the size of the codebase and that of the developers team working on the project* for the following reasons (non-exhaustive list):
When a codebase is large, the probability of certain parts of the code to be left untouched for a specific time period increases (as increases the duration of this "cold" period).
When new members join the team, you want them to be brought up to speed as soon as possible (and not get them frustrated in the process). "Overviewability" helps provide a good high-level abstraction of the whole project and usually also gives a good sense of how things work (more often than not it creates a feeling of familiarity; it's as if you've seen the codebase before - although you haven't).
"So, OK, "overviewability" is important. That's why we have this nice, component-centric structure etc. But why prefixing each file with the component's name ?"
Well, it might sound funny, but prefixing all component-related filenames ensures a specific order. E.g. the HTML partial or the CSS will always appear before the controllers etc:
...
userlogin.html
userlogin-controller.js
...
Where it not for the prefix, you would end up with various orders depending on the name of the component. E.g.:
... ... ...
controller.js controller.js bookself.html
... ... ...
service.js VS service.js VS controller.js
... ... ...
userlogin.html zombi.html service.js
... ... ...
Using a prefix ensures the files appear in specific order: controller comes always after the HTML partial, service also etc. E.g.:
... ... ...
userlogin.html zombi.html bookself.html
... ... ...
userlogin-controller.js VS zombi-controller.js VS bookself-controller.js
... ... ...
userlogin-service.js zombi-service.js bookself-service.js
... ... ...
This might seem trivial, but it's not; especially as one gets used to it.
Note that the human mind is very good at recognizing visual patterns (like the ones created by a tree-node representation of the folder- and file-structure in a file-explorer).
I.e. the controllers do not reside in a file named "<component>-controllers.js".
It resides in the first file whose name is significantly longer than the previous files.
The service (if any) resides in the file with the smaller name at the end, etc.
Mess that up (i.e. mess the order up because of the starting letter or mess their relative lengths up because of long/short component names) and you have yourself a situation similar to having to read something from the hard-drive, instead of just reading it from the RAM. (No developer wants to go there :))
*: Actually, it's what we call the "dev team flux" that is important here, i.e. how often a team member will leave (e.g. to work on something else, leaving the company etc) or a new member will be introduced.
Usually, the larger the team, the greater the flux.
tl;dr; While the other answers aren't wrong in most of their points, they fail to recognize the importance of the file navigation tools available today to developers.
Once we are fairly well acquainted with a project, we will want to navigate between files without looking at the source tree. Our naming scheme will play an important part in allowing us to navigate quickly. We can navigate to a file extremely quickly by entering fragments of the file name. For example, if your module's name is forsee
you can see a list of forsee
javascript files by typing fo.js
in a file search box (assuming your editor has this feature). The Chrome Dev Tools Source tab has this feature built-in. You can see it in action, here (open the dev tools and press Cmd+O):
I used to think that prepending all file names with the module name was necessary to search effectively, but then realized that isn't true at all. We can just as effectively search for fo/js
:
So now it should be clear that we can just as quickly navigate to a file regardless of whether or not the module name is prepended to the filename.
I agree with ExpertSystem that grouping files together allows you to see things better at a glance. However, once again prepending the module name isn't really necessary. Rather, activate the appropriate option in your editor:
In the screenshot above, I activated the Sort by Type option to enable sorting files by their file extensions.
If coding on a small screen (ie., laptop) and using a left-hand rail tree view to navigate the folder structure, the limited screen real estate will be better served by shorter file names. The module folder name will be visible so it's not useful to see that name repeated for every file.
Obviously, most of what I presented above does rely on developers using the right tools and knowing how to use them well. If your team does not have these tools or you doubt their ability to use them effectively, train them, or stick with the extra-verbose naming scheme.
With the advanced tools available to developers today, repeating the module name for every file is anachronistic. However, overly verbose file naming doesn't cause any great harm or efficiency problems. When structuring a new project, there are many other architectural decisions we'll have to make that are far more important than this one.
BTW: I do name js files according to ExpertSystems suggestion. Ie., dialog.js
, dialog-ctrl.js
, dialog-services.js
, etc. This makes sense for the reasons he stated, but when a module has multiple partials it's best not to follow this naming pattern for html files.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With