#19 [add] Javascript comments

Author: ui2code

translations/pt_BR/README.md

@@ -7,7 +7,7 @@
 
 * [ORIGINAL](https://github.com/hemersonvianna/code-style-guidelines/)
 
-## Sumário
+## Summary
 
 1. [Global](#global)
   * [Identation](#identation)
@@ -87,6 +87,8 @@ insert_final_newline = true
 trim_trailing_whitespace = false
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 ### Commits
 
 #### English
@@ -120,6 +122,8 @@ git commit -m "#10 [add] readme with the rules"
 git commit -m "my first commit"
 ```  
 
+**[⬆ voltar ao topo](#summary)**
+
 ### HTML
 
 #### HTML Syntax
@@ -144,6 +148,7 @@ Não use o caractere `/`, para elementos que não tem tem tag de fechamento
 <img src="..." alt="..." />
 ```
 
+**[⬆ voltar ao topo](#summary)**
 
 #### HTML Comments
 
@@ -177,6 +182,8 @@ O ideal é que os comentários não estejam no ambiente de produção, sendo ape
 <div></div>
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 #### HTML Character Encoding
 
 Sempre use `UTF-8`
@@ -187,6 +194,8 @@ Sempre use `UTF-8`
 </head>
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 #### HTML Attribute Order
 
 A ordem de atributos facilita a leitura e organização
@@ -204,6 +213,8 @@ A ordem de atributos facilita a leitura e organização
 <img class="..." src="..." alt="...">
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 #### HTML Performance
 
 Se for necessário ter script externo dentro da tag `head`, sempre deve estar por último.
@@ -249,6 +260,8 @@ Eliminar espaços e comentários, sem dúvida trazem uma melhor performance e s
 </html>
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 #### HTML Base Code
 
 HTMl básico que uso para os projetos
@@ -311,6 +324,8 @@ Tags meta que mais uso.
 <link rel="canonical" href="Url">
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 ### CSS
 
 #### CSS Syntax
@@ -436,6 +451,8 @@ Não especificar a unidade para valor `0`, exceto para a propriedade `rotate`.
 }
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 #### CSS Comments
 
 Os comentários sempre estarão antes do código a que se refere.
@@ -456,6 +473,8 @@ Os comentários sempre estarão antes do código a que se refere.
    ========================================================================== */
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 #### CSS Declaration Order
 
 A declaração das propriedades, devem ser em ordem alfabética.
@@ -478,6 +497,8 @@ A declaração das propriedades, devem ser em ordem alfabética.
 }
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 #### CSS Name
 
 Use `camelCase` para nomes compostos
@@ -530,6 +551,8 @@ Escolha nomes que dão significado a função da mesma.
 .sb { ... }
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 #### CSS Performance
 
 Não use IDs
@@ -597,6 +620,8 @@ Eliminar espaços e comentários, no ambiente de produção.
 }
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 #### CSS Media Queries
 
 Sempre comece o desenvolvimento em `Mobile first`
@@ -649,6 +674,8 @@ Mantenha as regras para um seletor em dispositos móveis e demais dispositos, se
 }
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 ### Javascript
 
 #### Javascript Syntax
@@ -754,8 +781,101 @@ if (foo == 'foo') {
 }
 ```
 
+**[⬆ voltar ao topo](#summary)**
+
 #### Javascript Comments
 
+Use `//` para comentário de uma linha
+
+```javascript
+// Good
+// Description
+
+// Bad
+/**
+ * Description
+ */
+```
+
+Use o comentário de uma linha acima do código referente. 
+
+```javascript
+// Good
+// set the default status to true
+const status = this._status || true;
+
+// Bad
+const status = this._status || true; // set the default status to true
+```
+
+Use `/** ... */` para blocos de comentários
+
+```javascript
+// Good
+/**
+ * Description
+ * @param {String} Description of the param
+ */
+
+// Bad
+//
+// Description
+//
+```
+
+Pode ter comentários com prefixo de ação.
+
+- FIXME - um problema que precisa ser revisto
+- TODO  - sugestão de uma solução para o problema que precisa ser implementado
+
+```javascript
+// FIXME: shouldn't use a global here
+total = 0;
+
+// TODO: total should be configurable by an options param
+this.total = 0;
+```
+
+Uma sugestão de sintaxe para escrever os comentários é o do [JSDuck](https://github.com/senchalabs/jsduck/wiki).
+
+```javascript
+/**
+ * @class Class name
+ * @param {String} Description of the param
+ * @extends name of the 
+ * Documentation for the class
+ */
+
+ /**
+ * @event click
+ * Documentation for the event
+ * @param {String} Description of the param
+ */
+
+/**
+ * @method Method name
+ * Documentation for the method
+ * @param {String} Description of the param
+ * @return {String} Description of the return
+ */
+
+/**
+ * @property {Boolean} [property=false]
+ * Description
+ */
+
+/**
+ * @class Class name
+ * Documentation for the class
+ *
+ * @constructor
+ * Documentation for the constructor
+ * @param {String} Description of the param
+ */
+```
+
+**[⬆ voltar ao topo](#summary)**
+
 #### Javascript Variables
 
 #### Javascript Performance