diff --git a/1-js/03-code-quality/02-coding-style/1-style-errors/solution.md b/1-js/03-code-quality/02-coding-style/1-style-errors/solution.md index f9b6ef964..3fccd9a61 100644 --- a/1-js/03-code-quality/02-coding-style/1-style-errors/solution.md +++ b/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 {" diff --git a/1-js/03-code-quality/02-coding-style/1-style-errors/task.md b/1-js/03-code-quality/02-coding-style/1-style-errors/task.md index b005fc85a..901e42ed6 100644 --- a/1-js/03-code-quality/02-coding-style/1-style-errors/task.md +++ b/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) diff --git a/1-js/03-code-quality/02-coding-style/article.md b/1-js/03-code-quality/02-coding-style/article.md index f9227952f..5b7f5bc99 100644 --- a/1-js/03-code-quality/02-coding-style/article.md +++ b/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,7 +103,7 @@ 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 @@ -112,18 +111,18 @@ 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 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.