Consistent and Minimal
Most important rules: Be consistent. Be minimal. Read these sections carefully.
we adopted LIFT principles:
- Locating our code is easy
- Identify code at a glance
- Flat structure as long as we can
- Try to stay DRY (Don’t Repeat Yourself) or T-DRY
Easy to locate via tree structure that its path splits up according to modules and subjects.
Identify at glance
The path of the file tells what it is:
pkg: this is a source code module (package...), as opposed to
docthat holds documents.
www: this is the web-site package.
hola: this is the holaspark.com web-site (we have also holacdn.com and other sites).
pub: this is the 'public' browser client side part of the site, as opposed to the server side nodejs part of the site.
inc: this is the fragments that included by html pages.
navbar.html: this is the navigation bar fragment included by all pages of the holaspark.com site.
Don't open a new subdir, unless you have at least 7 files in the current
We avoid this deep and unnecesary neasting of directories that 'Java' programmers love: Deep dir Java example from github:
/Lightning-Browser /gradle /app /src /main /java: 1 dir /acr: 1 dir /browser: 1 dir /lightning: finially the source code begins...
We would have arranged it:
Lightning-Browser /gradle /src: the source code begins! (was Lightning-Browser/app/src/main/java/acr/browser/lightning)
Try to stay DRY
Try not repeat yourself, but don't take it to the extreeme.
If its a large function, avoid repetition by moving it into a shared
directory, and make it 'utility'.
This also helps preventing the need to repeat the unit-tests.
But, if its a tiny 1 or 2 line function, its not always
worth the effort preventing repetition, since the modularization,
importing, and sharing this code my sometimes be longer that
just duplicating the tiny function, and will make the
code less 'stand alone' due to the additional importing.
Don't repeat name
The path is part of the name - don't repeat the path name in the filename:
Short and concise names, taking into account that the path name already provides a lot of into on the file's purpose.
_ as word splitter, just like
JS var name conventions
avoid spaces and any special chars. Use
Technical simplified english
Names should be in technical simplified english (as opposed to 'correct english'). Use simple present tense.
Simple present tense.
Normally avoid plural. Use it only when both plural and singular exist.
Web applications: NodeJS code in the root, public client browser files
under pub: JS and HTML at the root,
/css for css,
/img for images,
/inc for html fragments.
AngularJS: Component oriented.
Split into files/directories according to components/features, not accoding to directive/controller/service/view/route.