Consistent and Minimal

Most important rules: Be consistent. Be minimal. Read these sections carefully.

LIFT

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 locate

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/www/hola/pub/inc/navbar.html

• pkg: this is a source code module (package...), as opposed to doc that 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.

Flat structure

Don't open a new subdir, unless you have at least 7 files in the current directory.
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:

pkg/svc/dashboard/pub/dashboard_main.js pkg/svc/dashboard/pub/main.js

Naming

Short and concise names, taking into account that the path name already provides a lot of into on the file's purpose.

Unix notation

lower case.

Controller.HTML Controller.html controller.html

use _ as word splitter, just like JS var name conventions

loginApprove.html login_approve.html

avoid spaces and any special chars. Use _.

login.approve.html login-approve.html login_approve.html

Technical simplified english

Names should be in technical simplified english (as opposed to 'correct english'). Use simple present tense.

walk_through_the_tree_and_show_results.html result.html walk.html

Simple present tense.

walker.js walk.js removal.js remove.js

Normally avoid plural. Use it only when both plural and singular exist.

referrals.js referral.js results.js result.js customers.js // tables of all customer customer.js // view/edit a single customer

Templates

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.

/app.js /login.js /pub/index.html /pub/download.html /pub/main.js /pub/login.js /pub/inc/navbar.html /pub/css/main.css /pub/img/logo.png

AngularJS: Component oriented.
Split into files/directories according to components/features, not accoding to directive/controller/service/view/route.

/pub/main_directives.js /pub/main_controllers.js /pub/main_services.js /pub/main_views.js /pub/login.js /pub/navbar.js /pub/referral.js /pub/download.js