Nowadays I feel a great need to be prodcutive. The best way to accomplish this, is to use the same pattern, conventions and guides in all my projects. But there are so many rules and guides out there than it can be a little confusing.
So, in order words I felt it was about time to define My Coding Style.
This coding style is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
"All code in any code-base should look like a single person typed it, no matter how many people contributed."
Every commit message, pull request title or issue discussion must be in English.
Reason: English is the universal language nowadays, if you use any other language you're excluding potencial contributors.
Don't use Past or Present Continuous tenses for commit messages, those should be in Imperative Present tense.
// Good
Add feature X
// Bad
Added feature X
Adding feature XReason: This preference comes from Git itself.
When releasing a new version, write a commit message in the following format "Release - v1.0.0" instead of "v1.0.0".
Reason: Makes it easier to track version releases in git history. For example, you could run
git log --pretty=format:"%H %s" | grep 'Release'to fetch only version bump commits.
Don't commit big files unless they're absolutely required. Big files lead to big git history and it will be a pain for others to use the repo.
Include these files, or directory, in the .gitignore.
Always use HTML 5 doctype.
<!DOCTYPE html>Reason: As days goes by the amount of HTML5 valid markups is increasing, so it's better to use a simple doctype and stick with valid HTML4 and 5 tags.
Always use 2 spaces for indentation.
<!DOCTYPE html>
<html>
<head>
<title> Page Title</title>
<link rel="stylesheet" href="css/style.css">
</head>
<body>
...
</body>
</html>Reason: TODO.
Using the right meta tags can inscrease the relevance in search engines and be a meaningful help for user agents. This said, there are some meta tags that are worth taking a look at:
<meta name="description" content="A brief description about the website">
<meta name="keywords" content="html, php, javascript, css, markdown, git">
<meta name="robots" content="index">
<meta name="language" content="en-US">
<meta name="author" content="Cassio Cardoso">Reason: It is important to use meta tags to make the web site more relevant for search engines.
Put all CSS in one directory, commonly the css directory. When using a preprocessor stick with the plan and build all necessary .css files in one directory.
Link all the CSS files on the top of the page.
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" type="text/css" media="screen" href="css/main.css">
<link rel="stylesheet" type="text/css" media="screen" href="css/theme.css">
</head>
<body>
...
</body>
</html>Put all JS in one directory, commonly the js directory. Put all the js requisitions at the bottom of the page.
<!DOCTYPE html>
<html>
<head>
...
</head>
<body>
<script type="text/javascript" src="js/myscript.js">
</body>
</html>Never use inline style! Always put all styling in different .css files and link them in the header of the page.
Reason: "It's like crossing the streams in Ghostbusters. It's just not a good idea." - Chris Coyier (in reference to smoething completely unrelated)
Never use inline JS. We're not in 1996 anymore. All JS scripts must be written in a separate file and then inserted into the page.
Reason: TODO.
Use some kind of HTML Validator to make sure the code is written the best way possible.
Some validators options:
Reason: TODO.
Always write tag names in lowercase.
<hmtl>
<head>
...
</head>
<body>
...
</body>
</html>Always use h1 - h6 tags to define titles in the web page. If writting an article reserve h1 tag for the article title and then use the others to separate the article sections.
There's another good point that it's good for both semantic and SEO reasons so, why not?
<h1>Page/Article Title</h1>
<h2>Article Section Title</h2>
<h3>Sub-Section Title</h3>Reason: TODO.
Always use the alt attribute for images. It's both important for validation and accessibility and it takes only 1 minute.
<img src="path/to/img.jpg" alt="Image Alternative Text">Reason: TODO.
Use fieldset and labels in forms. This will help make the form more understandable for users.
<fieldset>
<label for="name">Name:</label><input type="text" id="name" name="name">
<label for="email">Email:</label><input type="text" id="email" name="email">
</fieldset>The unit of indentation is 2 spaces. Never mix spaces and tabs.
// Good
.class {
properties
}
// Bad
.class {
properties
}Reason: TODO
Use hyphens between class names instead of camelCase or under_score.
// Good
.my-class {
properties
}
// Bad
.myClass, my_class {
properties
}Reason: TODO
Always use lowercase hex colors instead of color names, and whenever possible use the reduced version.
// Good
.class {
background-color: #fff;
}
// Bad
.class {
background-color: white;
}Reason: TODO
The unit of indentation is 2 spaces. Never mix spaces and tabs.
// Good
while (condition) {
statements
}
// Bad
while (condition) {
statements
}Reason: TODO
Avoid lines longer than 100 characters. When a statement will not fit on a single line, it may be necessary to break it. Place the break after an operator, ideally after a comma. The next line should be indented 2 spaces.
// Good
YUI().use('aui-module-a', 'aui-module-b', 'aui-module-c', 'aui-module-d',
'aui-module-e', 'aui-module-f');
// Bad
YUI().use('aui-module-a', 'aui-module-b', 'aui-module-c', 'aui-module-d', 'aui-module-e', 'aui-module-f');Every project should contain a .editorconfig file that automatically set some indentation definitions. Make sure to install Editor Config's plugin on your code editor and you'll be all set.
Reason: TODO
Use JSHint to detect errors and potential problems.
The options for JSHint are stored in a .jshintrc file.
Reason: TODO
Relying on ASI (Automatic Semicolon Insertion) can cause hard to debug problems, so don't do it. Always use semicolons.
// Good
a = b + c;
test();
// Bad
a = b + c
test()Reason: TODO
All variables should be declared before used. Avoid multiple var statements.
// Good
var foo = '',
bar = '';
// Bad
var foo = '';
var bar = '';Constants (variables with permanent values) are written uppercase.
// Good
var FOO = 'foo';
// Bad
var foo = 'foo';Reason: TODO
Prefer single quotes over double quotes.
// Good
var string = '<p class="foo">Lorem Ipsum</p>';
// Bad
var string = "<p class='foo'>Lorem Ipsum</p>";Hexidecimal colors are written lowercase.
// Good
var color = '#d96ab6';
// Bad
var color = '#D96AB6';Reason: TODO
Parentheses () and commas , are not followed by indented children on new lines.
// Good
YUI().use('aui-module', function (Y) {
statements
});
// Bad
YUI().use(
'aui-module',
function (Y) {
statements
}
);Curly brackets {} are followed by new lines and indented children.
// Good
if (condition) {
statements
}
else {
statements
}
// Bad
if (condition) {
statements
} else {
statements
}Reason: TODO
Add spaces between operators (=, >, *, etc).
// Good
for (i = 0; i < 10; i++) {
statements
}
// Bad
for (i=0;i<10;i++) {
statements
}Both function expressions and function declarations doesn't have a space between the function keyword and the function name.
// Good
var foo = function() {
statements
};
// Bad
var foo = function () {
statements
};
// Good
function bar() {
statements
}
// Bad
function bar () {
statements
}Add spaces outside parentheses () but avoid it inside.
// Good
if (x > 10) {
statements
}
// Bad
if( x > 10 ){
statements
}Empty lines have no trailing spaces.
Reason: TODO
Avoid inline conditionals. Every conditional (with single or multiple statements) should use curly brackets {}. The only exception to this rule is else if.
// Good
if (condition) {
statements
}
else if (condition) {
statements
}
else {
statements
}
// Bad
if (condition) statement;
else if (condition) statement;
else statement;Reason: TODO
Strict equality checks === should be used in favor of ==.
// Good
if (foo === 'foo') {
statement
}
// Bad
if (foo == 'foo') {
statement
}
// Good
if (bar !== 'bar') {
statement
}
// Bad
if (bar != 'bar') {
statement
}Reason: TODO
Avoid inline loops. Every loop (with single or multiple statements) should use curly brackets {}.
// Good
for (initialization; condition; expression) {
statements
}
// Bad
for (initialization; condition; expression) statement;Reason: TODO
"If something needs to be written, it must be written in Markdown." - Cassio Cardoso (yes, I'm quoting myself!)
Always put one space between the title and the #.
Always separate titles from text with one new line. It increases text legibility without changing the way the markdown file is rendered.
When available, use GFM (GitHub Flavored Markdown).
Heavily inspired by: