Este é um documento vivo e novas idéias para melhorar os códigos correspondentes são sempre bem vindas. Contribua: faça fork, clone, branch, commit, push, pull request.
- Rick Waldron @rwaldron, github
- Mathias Bynens @mathias, github
- Schalk Neethling @ossreleasefeed, github
- Kit Cambridge @kitcambridge, github
- Raynos github
- Matias Arriola @MatiasArriola, github
- Idan Gazit @idangazit, github
- Leo Balter @leobalter, github
Todo código em qualquer aplicação deve parecer como se fosse escrito por uma única pessoa, independente de quantas pessoas tenham contribuído.
A lista a seguir descreve as práticas que eu uso em todo código onde sou o autor original; contribuições em projetos que eu criei devem seguir essas mesmas orientações.
Eu não tenho a intenção de impor minhas preferências por estilos nos códigos de outras pessoas; se eles seguem um estilo em comum - isso deve ser respeitado.
"Parte de ser um bom gestor de um projeto bem sucedido é perceber que escrever código para si mesmo é uma má idéia™. Se milhares de pessoas estão utilizando o seu código, então escreva o seu código com máxima clareza, não sob a sua preferência pessoal sobre como ser esperto com uma especificação." - Idan Gazit
Deve ser considerado o seguinte: 1) incompleto; e 2) LEITURA OBRIGATÓRIA. Eu não concordo sempre com os estilos escritos pelos autores abaixo, mas uma coisa é certa: Eles são consistentes. Além disso, esses são autoridades na linguagem.
- Eloquent JavaScript
- JavaScript, JavaScript
- Rebecca Murphey or Adventures in JavaScript Development
- Perfection Kills
- Douglas Crockford's Wrrrld Wide Web
Projetos devem sempre tentar incluir alguns formatos genéricos para que o código fonte possa ser compactado no preparo para uso em produção. Algumas ferramentas populares e testadas incluem o Uglify.js feito em JavaScript, assim como o Google Closure Compiler e YUI Compressor feitos em Java. Escolha um e apoie o mesmo.
Você pode encontrar um "build kit" funcional e genérico no diretório /kits deste repositório. A Utilização é simples: 1) copie o conteúdo de um dos kits encontrados em /kits para um novo diretório, 2) grave o arquivo .js de seu projeto no diretório /src, 3) coloque o nome do projeto dentro de project.txt, 4) execute o make pela linha de comando. (Caminho mais fácil: troque as ocorrências de "foo")
Projetos devem incluir alguma forma de teste unitário, por referência, de implementaçao ou funcional. Demonstrações de casos de uso NÃO SE QUALIFICAM como "testes". A lista a seguir contém frameworks de testes, nenhuma delas é considerada melhor que as demais.
- Espaço em Branco
- Sintaxe Bonita
- Checagem de Escrita (Cortesia das Recomendações de Estilo do Núcleo do jQuery)
- Avaliação Condicional
- Estilo Prático
- Nomenclatura
- Miscelâneas
- Objetos Nativos e Hospedados
- Comentários
-
- Nunca misture espaços e tabs.
- Quando começar um projeto, antes de escrever qualquer código, escolha entre indentação suave (espaços) ou tabulação real (tabs) - isso é lei.
- Pela legibilidade, eu sempre recomendo que configure o tamanho de indentação de seu editor para dois caracteres - isso significa dois espaços ou dois espaços representando um tab real.
- Se o seu editor suportar, sempre trabalhe com a configuração de "mostrar caracteres invisíveis" ligada. Os benefícios desta prática são:
- Fortalecer a consistência
- Eliminação de espaço em branco ao final da linha
- Eliminação de espaços em uma linha em branco
- Leituras de commits e diffs ficam mais legíveis
-
A. Parênteses, Chaves e Quebras de Linhas
// if/else/for/while/try sempre tem espaços, chaves e ocorrem em múltiplas linhas // isso facilita a legibilidade // 2.A.1.1 // Exemplos de código pouco claro/bagunçado if(condicao) facaAlgo(); while(condicao) iteracao++; for(var i=0;i<100;i++) algumaIteracao(); // 2.A.1.1 // Use espaço em branco para facilitar a leitura if ( condicao ) { // instruções } while ( condicao ) { // instruções } for ( var i = 0; i < 100; i++ ) { // instruções } // Ainda melhor: var i, length = 100; for ( i = 0; i < length; i++ ) { // instruções } // Ou... var i = 0, length = 100; for ( ; i < length; i++ ) { // instruções } var prop; for ( prop in object ) { // instruções } if ( true ) { // instruções } else { // instruções }
B. Atribuições, Declarações, Funções ( Nomenclatura, Expressão, Construtor )
// 2.B.1.1 // Variáveis var foo = "bar", num = 1, undef; // Notações Literais: var array = [], object = {}; // 2.B.1.2 // Utilizando apenas um `var` por escopo (função) promove legibilidade // e mantém a sua lista de declaração livre de desordem (além de evitar algumas tecladas) // Ruim var foo = ""; var bar = ""; var qux; // Bom var foo = "", bar = "", quux; // ou.. var // comentário aqui foo = "", bar = "", quux;
// 2.B.2.1 // Declaração de Função Nomeada function foo( arg1, argN ) { } // Utilização foo( arg1, argN ); // 2.B.2.2 // Declaração de Função Nomeada function square( number ) { return number * number; } // Utilização square( 10 ); // Estilo de passagem artificialmente contínua function square( number, callback ) { callback( number * number ); } square( 10, function( square ) { // instruções de callback }); // 2.B.2.3 // Expressão de Função var square = function( number ) { // Retorna algo de valor e relevante return number * number; }; // Expressão de Função com Identificador // Esse formato preferencial tem o valor adicional de permitir // chamar a si mesmo e ter uma identidade na pilha de comandos: var factorial = function factorial( number ) { if ( number < 2 ) { return 1; } return number * factorial( number-1 ); }; // 2.B.2.4 // Declaração de Construtor function FooBar( options ) { this.options = options; } // Utilização var fooBar = new FooBar({ a: "alpha" }); fooBar.options; // { a: "alpha" }
C. Exceptions, Slight Deviations
// 2.C.1.1 // Functions with callbacks foo(function() { // Note there is no extra space between the first paren // of the executing function call and the word "function" }); // Function accepting an array, no space foo([ "alpha", "beta" ]); // 2.C.1.2 // Function accepting an object, no space foo({ a: "alpha", b: "beta" }); // Inner grouping parens, no space if ( !("foo" in obj) ) { }
D. Consistency Always Wins
In sections 2.A-2.C, the whitespace rules are set forth as a recommendation with a simpler, higher purpose: consistency. It's important to note that formatting preferences, such as "inner whitespace" should be considered optional, but only one style should exist across the entire source of your project.
// 2.D.1.1 if (condition) { // statements } while (condition) { // statements } for (var i = 0; i < 100; i++) { // statements } if (true) { // statements } else { // statements }
E. End of Lines and Empty Lines
Whitespace can ruin diffs and make changesets impossible to read. Consider incorporating a pre-commit hook that removes end-of-line whitespace and blanks spaces on empty lines automatically.
-
Type Checking (Courtesy jQuery Core Style Guidelines)
3.A Actual Types
-
String:
typeof variable === "string" -
Number:
typeof variable === "number" -
Boolean:
typeof variable === "boolean" -
Object:
typeof variable === "object" -
Array:
Array.isArray(arrayObject)(wherever possible) -
null:
variable === null -
null or undefined:
variable == null -
undefined:
-
Global Variables:
typeof variable === "undefined"
-
Local Variables:
variable === undefined
-
Properties:
object.prop === undefinedobject.hasOwnProperty( prop )"prop" in object
-
JavaScript is a dynamically typed language - which can be your best friend or worst enemy, so: Always respect
type, as recommended.3.B Coerced Types
Consider the implications of the following...
Given this HTML:
<input type="text" id="foo-input" value="1">
// 3.B.1.1 // `foo` has been declared with the value `0` and its type is `number` var foo = 0; // typeof foo; // "number" ... // Somewhere later in your code, you need to update `foo` // with a new value derived from an input element foo = document.getElementById("foo-input").value; // If you were to test `typeof foo` now, the result would be `string` // This means that if you had logic that tested `foo` like: if ( foo === 1 ) { importantTask(); } // `importantTask()` would never be evaluated, even though `foo` has a value of "1" // 3.B.1.2 // You can preempt issues by using smart coercion with unary + or - operators: foo = +document.getElementById("foo-input").value; ^ unary + operator will convert its right side operand to a number // typeof foo; // "number" if ( foo === 1 ) { importantTask(); } // `importantTask()` will be called
Here are some common cases along with coercions:
// 3.B.2.1 var number = 1, string = "1", bool = false; number; // 1 number + ""; // "1" string; // "1" +string; // 1 +string++; // 1 string; // 2 bool; // false +bool; // 0 bool + ""; // "false"
// 3.B.2.2 var number = 1, string = "1", bool = true; string === number; // false string === number + ""; // true +string === number; // true bool === number; // false +bool === number; // true bool === string; // false bool === !!string; // true
// 3.B.2.3 var array = [ "a", "b", "c" ]; !!~array.indexOf( "a" ); // true !!~array.indexOf( "b" ); // true !!~array.indexOf( "c" ); // true !!~array.indexOf( "d" ); // false var num = 2.5; parseInt( num, 10 ); // is the same as... ~~num;
-
-
// 4.1.1 // When only evaluating that an array has length, // instead of this: if ( array.length > 0 ) ... // ...evaluate truthiness, like this: if ( array.length ) ... // 4.1.2 // When only evaluating that an array is empty, // instead of this: if ( array.length === 0 ) ... // ...evaluate truthiness, like this: if ( !array.length ) ... // 4.1.3 // When only evaluating that a string is not empty, // instead of this: if ( string !== "" ) ... // ...evaluate truthiness, like this: if ( string ) ... // 4.1.4 // When only evaluating that a string _is_ empty, // instead of this: if ( string === "" ) ... // ...evaluate falsy-ness, like this: if ( !string ) ... // 4.1.5 // When only evaluating that a reference is true, // instead of this: if ( foo === true ) ... // ...evaluate like you mean it, take advantage of it's primitive capabilities: if ( foo ) ... // 4.1.6 // When evaluating that a reference is false, // instead of this: if ( foo === false ) ... // ...use negation to coerce a true evaluation if ( !foo ) ... // ...Be careful, this will also match: 0, "", null, undefined, NaN // If you _MUST_ test for a boolean false, then use if ( foo === false ) ... // 4.1.7 // When only evaluating a ref that might be null or undefined, but NOT false, "" or 0, // instead of this: if ( foo === null || foo === undefined ) ... // ...take advantage of == type coercion, like this: if ( foo == null ) ... // Remember, using == will match a `null` to BOTH `null` and `undefined` // but not `false`, "" or 0 null == undefined
ALWAYS evaluate for the best, most accurate result - the above is a guideline, not a dogma.
// 4.2.1 // Type coercion and evaluation notes Prefer `===` over `==` (unless the case requires loose type evaluation) === does not coerce type, which means that: "1" === 1; // false == does coerce type, which means that: "1" == 1; // true // 4.2.2 // Booleans, Truthies & Falsies Booleans: true, false Truthy are: "foo", 1 Falsy are: "", 0, null, undefined, NaN, void 0
-
// 5.1.1 // A Practical Module (function( global ) { var Module = (function() { var data = "secret"; return { // This is some boolean property bool: true, // Some string value string: "a string", // An array property array: [ 1, 2, 3, 4 ], // An object property object: { lang: "en-Us" }, getData: function() { // get the current value of `data` return data; }, setData: function( value ) { // set the value of `data` and return it return ( data = value ); } }; })(); // Other things might happen here // expose our module to the global object global.Module = Module; })( this );
// 5.2.1 // A Practical Constructor (function( global ) { function Ctor( foo ) { this.foo = foo; return this; } Ctor.prototype.getFoo = function() { return this.foo; }; Ctor.prototype.setFoo = function( val ) { return ( this.foo = val ); }; // To call constructor's without `new`, you might do this: var ctor = function( foo ) { return new Ctor( foo ); }; // expose our constructor to the global object global.ctor = ctor; })( this );
-
You are not a human code compiler/compressor, so don't try to be one.
The following code is an example of egregious naming:
// 6.1.1 // Example of code with poor names function q(s) { return document.querySelectorAll(s); } var i,a=[],els=q("#foo"); for(i=0;i<els.length;i++){a.push(els[i]);}
Without a doubt, you've written code like this - hopefully that ends today.
Here's the same piece of logic, but with kinder, more thoughtful naming (and a readable structure):
// 6.2.1 // Example of code with improved names function query( selector ) { return document.querySelectorAll( selector ); } var idx = 0, elements = [], matches = query("#foo"), length = matches.length; for( ; idx < length; idx++ ){ elements.push( matches[ idx ] ); }
A few additional naming pointers:
// 6.3.1 // Naming strings `dog` is a string // 6.3.2 // Naming arrays `dogs` is an array of `dog` strings // 6.3.3 // Naming functions, objects, instances, etc camelCase; function and var declarations // 6.3.4 // Naming constructors, prototypes, etc. PascalCase; constructor function // 6.3.5 // Naming regular expressions rDesc = //; // 6.3.6 // From the Google Closure Library Style Guide functionNamesLikeThis; variableNamesLikeThis; ConstructorNamesLikeThis; EnumNamesLikeThis; methodNamesLikeThis; SYMBOLIC_CONSTANTS_LIKE_THIS;
-
This section will serve to illustrate ideas and concepts that should not be considered dogma, but instead exists to encourage questioning practices in an attempt to find better ways to do common JavaScript programming tasks.
A. Using
switchshould be avoided, modern method tracing will blacklist functions with switch statementsThere seems to be drastic improvements to the execution of
switchstatements in latest releases of Firefox and Chrome. http://jsperf.com/switch-vs-object-literal-vs-moduleNotable improvements can be witnesses here as well: rwaldron#13
// 7.A.1.1 // An example switch statement switch( foo ) { case "alpha": alpha(); break; case "beta": beta(); break; default: // something to default to break; } // 7.A.1.2 // A better approach would be to use an object literal or even a module: var switchObj = { alpha: function() { // statements // a return }, beta: function() { // statements // a return }, _default: function() { // statements // a return } }; var switchModule = (function () { return { alpha: function() { // statements // a return }, beta: function() { // statements // a return }, _default: function() { // statements // a return } }; })(); // 7.A.1.3 // If `foo` is a property of `switchObj` or `switchModule`, execute as a method... ( Object.hasOwnProperty.call( switchObj, foo ) && switchObj[ foo ] || switchObj._default )( args ); ( Object.hasOwnProperty.call( switchObj, foo ) && switchModule[ foo ] || switchModule._default )( args ); // If you know and trust the value of `foo`, you could even omit the OR check // leaving only the execution: switchObj[ foo ]( args ); switchModule[ foo ]( args ); // This pattern also promotes code reusability.
B. Early returns promote code readability with negligible performance difference
// 7.B.1.1 // Bad: function returnLate( foo ) { var ret; if ( foo ) { ret = "foo"; } else { ret = "quux"; } return ret; } // Good: function returnEarly( foo ) { if ( foo ) { return "foo"; } return "quux"; }
-
The basic principal here is:
To reinforce this concept, please watch the following presentation:
<iframe src="http://blip.tv/play/g_Mngr6LegI.html" width="480" height="346" frameborder="0" allowfullscreen></iframe>http://blip.tv/jsconf/jsconf2011-andrew-dupont-everything-is-permitted-extending-built-ins-5211542
-
- JSDoc style is good (Closure Compiler type hints++)
- Single line above the code that is subject
- Multiline is good
- End of line comments are prohibited!
Any project that cites this document as its base style guide will not accept comma first code formatting unless explicitly specified otherwise.
See: https://mail.mozilla.org/pipermail/es-discuss/2011-September/016805.html Notable: "That is horrible, and a reason to reject comma first.", "comma-first still is to be avoided"
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent