- Webknit
- WON
- Base
Everyone tends to write code differently and there is no official right or wrong way.
I’ve recently been looking at how I write my code to try ensure it’s always consistent. I’m mainly looking at things like indention, spacing, ordering, grouping etc. I’m briefly covering my HTML, CSS, SASS and JS in this post.
You can look at my code by downloading my Front-End template.
<body>
<div class="demo-box">
<h1>Demo header</h1>
<p>Demo paragraph</p>
<nav class="demo-nav">
<ul>
<li class="demo-box__nav-link"><a>Home</a></li>
<li class="demo-box__nav-link demo-box__nav-link--right"><a>Home</a></li>
</ul>
</nav><!-- .demo-nav -->
</div><!-- .demo-box -->
</body>
I like to add spaces between every single containing element except for the block items such as <li>, <p>, <input> etc. I used to add spaces between every single line of code but I think grouping the “blocks” of visual content makes the code easier to both scan and read. Each new containing element is indented so that you can clearly see what’s contained by what.
I like to close all my elements with <!– .name –>. This is a personal choice which makes things neater and easier to read/scan/debug. I use the class/ID name inside the HTML comments.
I’ve recently started using BEM for my naming. You can read about it here. I’m relatively new to it so I’m still learning but it looks very useful, especially for larger scale projects.
.demo-box {
background: red;
width: 100px;
}
.demo-box__nav li {
float: left;
width: 30px;
}
.demo-box__nav-link {
colour: green;
}
.demo-box__nav-link--right {
float: right;
}
My CSS is “tighter” than my markup and is easy to read anyway with the lovely colourful syntax highlighting in the GUI text editor. I have the class/ID name followed by a space the the opening { followed by a new line, indent and my CSS. I like to have my class attributes in alphabetic order, you can read about that here.
Almost all of my files (CSS, JS, SASS) have a header that looks like the following. I want to make sure that I know exactly what the file is when I open it. These are just random things that I’ve added to my template, however I think a title and description is essential.
/* - BASE HTML TEMPLATE ------------------------------------------------- Description: Base/Main CSS styles Author: Shane Prendergast Author URL: http://www.webknit.co.uk Template URL: http://base.webknit.co.uk/ Notes: Base CSS styles and Mobile first approach. Consider mimifying your CSS for performance if using vanilla CSS. /*
I like to have an index at the top of my CSS to ensure I can easily locate a particular bit of code. Each individual part of code is split into a section in order to make it modular. Modular code is basically reusable code and there are various different approaches to writing modular HTML and CSS.
I add headers, index and section headers that look like the following. Each section has 2 spaces in-between.
/* - CONTENTS
-------------------------------------------------
- CSS Reset ............................ 1.0.
- HTML5 Reset .......................... 2.0.
- Global ............................... 3.0.
- Structural ........................... 3.1.
- Base Elements ........................ 3.2.
- Link Elements ........................ 3.3.
- Buttons .............................. 3.4.
- Form ................................. 3.5.
- Build elements ....................... 3.6.
- Mobile grid styles ................... 4.0.
- Wide Mobile .......................... 4.1.
- Tablet ............................... 4.2.
- Desktop .............................. 4.3.
- Example Section ...................... 5.0.
- @fontface ............................ 0.0.
*/
/*********************************************
- 1.0 - CSS RESET
*********************************************/
.body {
background: red;
}
The index list grows with my code. Each new CSS section I create is added to the the index with its title and number. Notice all the headers are in capitals and comments and general text in lowecase. This might sound really anal but I think it makes things much easier to read. You wouldn’t expect to read a book/magazine/newspaper with no structure and I think the same applies for code.
I now group all my media queries together in vanilla CSS. You can read about why that’s a good idea here.
/* - MOBILE
------------------------------------------ */
.example {
color: red;
}
/* - WIDE MOBILE
------------------------------------------ */
@media only screen and (min-width: 30em) {
.example {
color: blue;
}
}
/* - TABLET
------------------------------------------ */
@media only screen and (min-width: 48em){
.example {
color: yellow;
}
}
/* - DESKTOP
------------------------------------------ */
@media only screen and (min-width: 73.125em){
.example {
color: green;
}
}
I have re-wrote the CSS examples in SASS below for demonstration purposes. I try not go more than 3 levels deep. I NEVER go less than 4*. This basically means that you are being too specific. If you find yourself more than four levels deep then consider re-working your code.
*There may be some very very rare examples.
.demo-box {
background: red;
width: 100px;
.demo-box__nav li {
float: left;
width: 30px;
.demo-box__nav-link {
colour: green;
&.demo-box__nav-link--right {
float: right;
}
}
}
}
My SASS works the same as the CSS with the header and index. I add the imports within my main style.scss file. For example…
/********************************************* - 1.0 - SASS MODULES *********************************************/ /* - 1.1. - COLOURS, GRADIENTS, TYPOGRAPHY ------------------------------------------ */ @import "modules/_variables"; /* - 1.2. - FUNCTIONS ------------------------------------------ */ @import "modules/_functions"; /* - 1.2. - MIXINS ------------------------------------------ */ @import "modules/_mixins";
By doing this I can clearly see where a module or partial is located by quickly skimming the index. I often see a list of imports in developers main SASS files with no comments etc and I personally think that’s really messy. I think the need for organisation applies even more when you’re using SASS.
Modules
The modules directory is reserved for Sass code that doesn’t cause Sass to actually output CSS. Things like mixin declarations, functions, and variables.
SASS partials
The partials directory is where most of the CSS is constructed. I add partials as I go along ensuring my code is modular and reusable.
SASS mixins are very useful and can be used for a wide range of CSS. Think ahead and anything that you’re going to write twice such as border-box, round corner etc might as well belong inside a mixin. Even if they have different values you can pass conditional statements to the mixin. If you need more information on SASS you can find that here.
I’ve include my MQ mixin as an example below.
@mixin breakpoint($point) {
@if $point == wide-mobile {
@media only screen and (min-width: 30em) { @content; }
}
@else if $point == tablet {
@media only screen and (min-width: 48em) { @content; }
}
@else if $point == desktop {
@media only screen and (min-width: 73.125em) { @content; }
}
@else if $point == retina {
@media print, (-o-min-device-pixel-ratio: 5/4), (-webkit-min-device-pixel-ratio: 1.25), (min-resolution: 120dpi) { @content; }
}
}
and then I can write the actual SASS like this.
.example {
background: url(logo.jpg) top left no-repeat;
color: red;
@include breakpoint(wide-mobile) {
color: blue;
}
@include breakpoint(tablet) {
color: yellow;
}
@include breakpoint(desktop) {
color: green;
}
@include breakpoint(retina) {
background: url(logo2x.jpg) top left no-repeat;
background-size: 212px 303px;
}
}
I like my JS is very “spaced out”. Spaces in between everything expect those things that I think should be grouped. Including:
My main aim is to ensure I can clearly see chunks of JS. That way I’m making it easy for anyone to read – and understand – my code.
Base.functionName = function() {
var self = $(this);
var variable = $('.var');
function init() {
variable.click(functionOne);
function functionOne() {
//JS CODE
}
}
init();
};
In JavaScript it is very easy to create global variables that have the potential to interact in negative ways. The practice of namespacing is usually to create an object literal encapsulating your own functions and variables, so as not to collide with those created by other scripts/libraries.
var Base = Base || {};
I call my functions using $(document).ready shorthand code at the bottom of my JS file.
$(function() {
new Base.functionName();
});
Obviously lots more to it than that but these are some basic examples!
I try to ensure I stick to these styles with all the code I write. If I encounter a new piece of code, or something I haven’t done before then I consider how I think it should be written. Make sure you comment your code generously. When you minify the code all your comments will be removed so fill your SASS, CSS and JS with as many comments as it takes!
Whenever you write code you should consider would another developer be able to work on it as easily as you can?
Sometimes I think I’m going overboard with all this but in reality it makes me a much neater, and ultimately better developer. One thing I have found is that people have often proposed a different method of working and I’ve previously dismissed them. As I’ve matured as a developer I’m now always willing to give things a try and to see if they work out for me. It often takes time and patience but you’re learning something new along the way. There have been lots of occasions where I have seen the light and adopted the method.
If you’ve any suggestions or comments you can shoot me a .
Thanks for reading