Project Styleguide

This is an opinionated styleguide for the project, based on industry best practices and personal experience/preferences, with the purpose of ensuring high quality code for future development of the project and high productivity and communication within the team.

HTML

HTML5.

DONT ADD DIVS AND CLASSES THAT HAVE ONLY DESIGN PURPOSE, HTML IS FOR STRUCTURE AND CONTENT and should be minimal and readable. (So dont use Bootstrap).

Icons are an exception, but add a text replacement and check with the WAVE chrome extension.

CSS

Using SCSS and Compass.

Grunt is automaticly compiling to CSS.

Styling is like SMACSS - https://smacss.com/book/

Separated code into files in app/styles folder:

• base.scss - basic html tags at the top, and common reusable simple classes after that (but if the common class is a big one like "tables" or "forms", create a seprate SCSS file for it).
• forms.scss - forms html tags and reusable form and form validation classes
• icons.scss - using Compass to automaticly generate a sprite of icons with each image in app/images/icons, add any new icon to this folder.
• layout.scss - anything in the header, footer, main nav, and the basic page structure
• main.scss - just importing all other scss files together. Any other SCSS file - page specific modifications with unreusable styling. each page have a class name on the HTML body tag so use it to identify pages.

TODO: SCSS file for tables maybe.

Use any selectors and CSS3 features as long as it works in the latest versions of browsers and IE >= 10.

Only support IE9 when it's very easy to.

Don't use prefixed CSS3 tags when all latest versions of the common browsers already support the unprefixed.

Use the Compass way of inserting urls to the CSS, like image-url instead of url (so it will work when moving the project to another URL).

JavaScript

Using Angular 1.3 (with jQLight only, dont add the full jQuery).

The base project was created using Yeoman Angular generator, so using it's file structure.

Pay attention to JSHint warnings when Grunt is building the project, and fix them.

TODO: should break the build on JSHInt errors.

Add JS libs with Bower, don't download the zip and add to the project manually!

Use the controller As syntax, don't use $scope.

Use the rest.js service for all of the server interaction, the base REST url is set once in $rootScope so it can be easly changed.

Add comments for EVERYTHING.

Navigate to views (routes) using Angular's $location.path(XXX);

Browsers

Latest Chrome and Firefox, IE >= 10, but IE 9 will work for most stuff that is easy to support. IE 8 is not supported.

Comment in the relevent code when something is a fix for IE9 or won't work with IE9. (Now is March 2015, stop caring for IE9 when possible)

Not mobile optimized (Yet?).

Optimizing

Grunt is minimizing and optimizing everything to the /dist folder.

TODO: add PageSpeed test

Suff Grunt is automatically doing to optimize code: concat, cssmin, imagemin, htmlmin, ngAnnotate, cdnify, jshint

General

Learn to use Grunt (grunt serve and grunt build commands most importantly) before doing anything on the project - edit files only in /app folder.

The project should be standalone, work on any base URL and server. any Java (server side) stuff will communicate with this FED project via REST only.