Coding style

1-js/03-code-quality/02-coding-style/1-style-errors/solution.md

@@ -11,10 +11,10 @@ function pow(x,n)  // <- nenhum espaço entre argumentos
 }
 
 let x=prompt("x?",''), n=prompt("n?",'') // <-- tecnicamente possível,
-// mas o melhor é a tornar em 2 linhas, também não existem espaços, e falta o ;
-if (n<0)  // <- nenhum espaço dentro (n < 0), e deveria existir uma linha extra sobre a condição
+// mas o melhor é torná-la em 2 linhas, também não existem espaços, e falta o ;
+if (n<0)  // <- nenhum espaço dentro (n < 0), e deveria existir uma linha em branco sobre a instrução
 {   // <- chaveta de abertura numa linha em separado
-  // abaixo - linhas longas podem ser repartidas por múltiplas linhas para melhorar a legíbilidade
+  // a seguir - linhas longas podem ser repartidas por múltiplas linhas para melhor legibilidade
   alert(`A potência de ${n} não é suportada, por favor insira um número inteiro maior do que zero`);
 }
 else // <- poderia ser escrito numa única linha, como "} else {"

1-js/03-code-quality/02-coding-style/1-style-errors/task.md

@@ -4,7 +4,7 @@ importance: 4
 
 # Mau estilo
 
-O que há de errado com o código abaixo?
+O que há de errado com o estilo de código abaixo?
 
 ```js no-beautify
 function pow(x,n)

1-js/03-code-quality/02-coding-style/article.md

@@ -2,7 +2,7 @@
 
 O nosso código, deve ser o mais limpo e fácil de ler o quanto possível.
 
-Isto é, na verdade, a arte de programar -- tomar uma tarefa complexa e codificá-la de uma forma que tanto seja correta, como humanamente legível. Um bom estilo de código em muito ajuda para tal.
+Isto é, na verdade, a arte de programar -- tomar uma tarefa complexa e codificá-la de forma que seja tanto correta, quanto humanamente legível. Um bom estilo de código em muito ajuda para tal.
 
 ## Sintaxe
 
@@ -42,7 +42,7 @@ Nada está gravado em pedra aqui. Estas são preferências de estilo, não rígi
 
 ### Chavetas
 
-Em muitos projetos em JavaScript, as chavetas são escritas no estilo "Egípcio", com a de abertura na mesma linha que a palavra-chave correspondente -- não numa nova linha. Também deveria existir um espaço antes da chaveta de abertura, desta forma:
+Em muitos projetos de JavaScript, as chavetas são escritas no estilo "Egípcio", com a de abertura na mesma linha que a palavra-chave correspondente -- não numa nova linha. Também deveria existir um espaço antes da chaveta de abertura, desta forma:
 
 ```js
 if (condição) {
@@ -54,13 +54,13 @@ if (condição) {
 
 Uma construção de única-linha, tal como `if (condição) doSomething()`, é um importante caso de exceção. Devemos utilizar chavetas, ou não?
 
-Aqui estão variantes com anotações, para que por si mesmo você possa avaliar a sua legibilidade:
+Aqui estão variantes com anotações, para que você por si mesmo possa avaliar a sua legibilidade:
 
 1. 😠 Principiantes, por vezes fazem isto. É mau! As chavetas não são necessárias:
     ```js
     if (n < 0) *!*{*/!*alert(`A potência ${n} não é suportada`);*!*}*/!*
     ```
-2. 😠 Dividida por linhas em separado, sem chavetas. Nunca faça isso; é fácil cometer erros ao adicionar mais linhas:
+2. 😠 Dividir por linhas em separado, sem chavetas. Nunca faça isso; é fácil cometer erros ao adicionar mais linhas:
     ```js
     if (n < 0)
       alert(`A potência ${n} não é suportada`);
@@ -76,19 +76,18 @@ Aqui estão variantes com anotações, para que por si mesmo você possa avaliar
     }
     ```
 
-Para código muito curto, uma única linha é aceitável, ex: `if (cond) return null`. Mas, um bloco de código (a última variante) é geralmente mais legível.
+Para código muito curto, uma única linha é aceitável, ex: `if (cond) return null`. Contudo, um bloco de código (a última variante) é geralmente mais legível.
 
-### Comprimento da linha
+### Comprimento de linha
 
 Ninguém gosta de ler uma longa linha horizontal de código. A melhor prática é a particionar.
 
 Por exemplo:
 ```js
-// o acento grave (*backtick*) ` permite repartir uma *string* por múltiplas linhas
+// as aspas usando acento grave (*backtick*) ` permitem repartir uma *string* por múltiplas linhas
 let str = `
-  O TC39 da ECMA International, é um grupo de desenvolvedores e 
-  implementadores de JavaScript, académicos, e outros, colaborando com a comunidade 
-  para manter e evoluir a definição de JavaScript.
+  O TC39 da ECMA International, é um grupo de desenvolvedores e implementadores de JavaScript, académicos, e outros, colaborando com a comunidade para manter e
+  evoluir a definição do JavaScript.
 `;
 ```
 
@@ -104,26 +103,26 @@ if (
 }
 ```
 
-O máximo comprimento da linha deveria ser acordado entre os membros de uma equipa de trabalho. Geralmente, vai de 80 a 120 caráteres.
+O máximo comprimento de linha deveria ser acordado entre os membros de uma equipa de trabalho. Geralmente, vai de 80 a 120 caráteres.
 
 ### Indentação
 
 Existem dois tipos de indentação:
 
 - **Indentação horizontal: 2 ou 4 espaços.**
 
-    Uma indentação horizontal é feita quer inserindo 2 ou 4 espaços, quer usando símbolo de tabulação horizontal (tecla `key:Tab`). Qual deles escolher, vem sendo uma guerra antiga. Hoje em dia, os espaços são mais comuns.
+    Uma indentação horizontal é feita quer inserindo 2 ou 4 espaços, quer usando o símbolo de tabulação horizontal (tecla `key:Tab`). Qual deles escolher, vem sendo uma guerra antiga. Hoje em dia, os espaços são mais comuns.
 
     Uma vantagem dos espaços sobre *tabs*, é que espaços permitem configurações de indentação mais flexíveis do que o símbolo "Tab".
 
     Por exemplo, podemos alinhar os argumentos com o parêntese de abertura, desta forma:
 
     ```js no-beautify
-    show(parameters,
-         alinhada, // 5 espaços adicionados à esquerda  
-         uma,
+    show(parâmetros,
+         alinhados, // 5 espaços adicionados à esquerda  
+         um,
          após,
-         outra
+         outro
       ) {
       // ...
     }
@@ -145,7 +144,7 @@ Existem dois tipos de indentação:
     }
     ```
 
-    Insira uma nova linha extra onde ajudar a tornar o código mais legível. Não deveriam existir mais de nove linhas de código sem uma indentação vertical.
+    Insira uma linha em branco onde ajudar a tornar o código mais legível. Não deveriam existir mais de nove linhas de código sem uma indentação vertical.
 
 ### Pontos-e-vírgula
 
@@ -157,7 +156,7 @@ Se for programador de JavaScript experiente, poderá escolher um estilo de códi
 
 ### Níveis aninhados
 
-Tente evitar aninhar (*nesting*) código a muitos níveis de profundidade.
+Tente evitar aninhar (*nesting*) código em muitos níveis de profundidade.
 
 Por exemplo, num ciclo (*loop*) por vezes é boa ideia utilizar o comando ["continue"](info:while-for#continue) para evitar mais aninhamentos.
 
@@ -221,13 +220,13 @@ function pow(x, n) {
 }
 ```
 
-A segunda é mais legível, porque o "caso especial" `n < 0` é tratado cedo. Uma vez a verificação feita, podemos prosseguir para o fluxo "principal" do código, sem necessidade de aninhamento (*nesting*) adicional.
+A segunda é mais legível, porque o "caso especial" `n < 0` é tratado cedo. Uma vez a verificação feita, podemos prosseguir para o fluxo "principal" do código, sem necessidade de aninhamento adicional.
 
 ## Local da função
 
 Se estiver a escrever várias funções "auxiliares" (*"helper" functions*) acompanhadas do código que as utiliza, existem três formas para organizar as funções.
 
-1. Funções acima do código que as utiliza:
+1. Declare as funções *acima* do código que as utiliza:
 
     ```js
     // *!*declarações de funções*/!*
@@ -256,7 +255,7 @@ Se estiver a escrever várias funções "auxiliares" (*"helper" functions*) acom
     setHandler(elem);
     walkAround();
 
-    // --- *!*funções auxiliares (*helper functions*)*/!* ---
+    // --- *!*funções auxiliares*/!* ---
     function createElement() {
       ...
     }
@@ -279,7 +278,7 @@ Isto porque ao ler o código, queremos primeiro saber *o que faz*. Se o código
 
 Um guia de estilo contém regras gerais sobre "como escrever" código, ex. que aspas utilizar, quantos espaços indentar, qual o máximo comprimento de linha, etc. Uma quantidade de aspetos menores.
 
-Quando todos os membros de uma equipa usam o mesmo guia de estilo, o código parece uniforme, independentemente do membro da equipa que o tenha escrito.
+Quando todos os membros de uma equipa usam o mesmo guia de estilo, o código parece uniforme, independentemente do membro da equipa que o escreveu.
 
 Obviamente, que uma equipa pode sempre escrever o seu próprio guia de estilo, mas geralmente não há necessidade. Existem muitos guias à escolha.
 
@@ -295,26 +294,26 @@ Se for um programador iniciante, comece pela cábula (*cheatsheet*) disponível
 
 ## *Linters* Automatizados
 
-*Linters*, são ferramentas que automaticamente verificam o estilo do seu código e fazem sugestões para o alterar.
+*Linters*, são ferramentas que automaticamente verificam o estilo do seu código e fazem sugestões para o melhorar.
 
 O seu ponto-forte reside em, à medida que verificam o estilo, poderem encontrar alguns erros (*bugs*), como nomes de variáveis ou de funções mal-escritos. Devido a esta capacidade, é recomendado que use um *linter* mesmo que não queira aderir a um certo "estilo de código".
 
 Aqui estão algumas das mais conhecidas ferramentas de *linting*:
 
-- [JSLint](http://www.jslint.com/) -- um dos primeiros *linters*.
-- [JSHint](http://www.jshint.com/) -- mais configurações do que *JSLint*.
-- [ESLint](http://eslint.org/) -- provavelmente o mais recente.
+- [JSLint](https://www.jslint.com/) -- um dos primeiros *linters*.
+- [JSHint](https://jshint.com/) -- mais configurações do que *JSLint*.
+- [ESLint](https://eslint.org/) -- provavelmente o mais recente.
 
-Todos eles podem executar a tarefa. O autor utiliza [ESLint](http://eslint.org/).
+Todos eles podem executar a tarefa. O autor utiliza [ESLint](https://eslint.org/).
 
 Muitos *linters* estão integrados em editores populares: apenas ative a extensão (*plugin*) no editor e configure o estilo.
 
 Por exemplo, para o *ESLint* deveria efetuar o seguinte:
 
-1. Instale o [Node.js](https://nodejs.org/pt-br/).
-2. Instale o *ESLint* com o comando `npm install -g eslint` (*npm* é um instalador de pacotes [*package installer*] para JavaScript).
-3. Crie um ficheiro de configuração (*config file*) com o nome `.eslintrc` na raiz do seu projeto em JavaScript (na pasta que contém todos os seus ficheiros).
-4. Instale/ative a extensão (*plugin*) para o seu editor que faça a integração com o *ESLint*. A maior parte dos editores tem uma.
+1. Instalar o [Node.js](https://nodejs.org/pt-br/).
+2. Instalar o *ESLint* com o comando `npm install -g eslint` (*npm* é um instalador de pacotes para JavaScript).
+3. Criar um ficheiro de configuração (*config file*) com o nome `.eslintrc` na raiz do seu projeto de JavaScript (na pasta que contém todos os seus ficheiros).
+4. Instalar/ativar a extensão que faça a integração com o *ESLint* no seu editor. A maior parte dos editores tem uma.
 
 Aqui está um exemplo de um ficheiro `.eslintrc`:
 
@@ -333,7 +332,7 @@ Aqui está um exemplo de um ficheiro `.eslintrc`:
 }
 ```
 
-Aqui a diretiva `"extends"` denota que a configuração tem como base o conjunto de configurações em "eslint:recommended". Depois disso, podemos especificar as nossas próprias.
+Aqui a diretiva `"extends"` denota que a configuração tem como base o conjunto de configurações em "eslint:recommended". Depois dela, podemos especificar as nossas próprias.
 
 Também é possível descarregar conjuntos de regras de estilo da web e depois estendê-los. Veja em <http://eslint.org/docs/user-guide/getting-started> mais detalhes sobre a instalação.
 
@@ -343,6 +342,6 @@ De igual modo, certos *IDEs* (Ambientes de Desenvolvimento Integrado) têm *lint
 
 Todas as regras sintáticas descritas neste capítulo (e nos guias de estilo referenciados) têm como objetivo aumentar a legibilidade do seu código. Todas elas são questionáveis.
 
-Quando pensarmos em escrever "melhor" código, as questões que deveríamos nos perguntar são: "O que faz o código mais legível e mais fácil de compreender?" e "O que nos pode ajudar a evitar erros?" Estes são os principais aspetos a ter em mente ao escolher e debater estilos de código.
+Quando pensarmos em escrever "melhor" código, as questões que nos deveríamos perguntar são: "O que faz o código mais legível e mais fácil de compreender?" e "O que nos pode ajudar a evitar erros?" Estes são os principais aspetos a ter em mente ao escolher e debater estilos de código.
 
-A leitura de guias de estilo populares, permite-nos estar a par das mais recentes ideias sobre tendências, e melhores práticas, de estilos de código.
+A leitura de guias de estilo populares nos permite estar a par das mais recentes ideias sobre tendências, e melhores práticas, de estilos de código.