From efc343f10b001e07ad3cc3204e15138dfbac61ac Mon Sep 17 00:00:00 2001 From: Weiglas Date: Sun, 4 Oct 2020 15:37:29 -0300 Subject: [PATCH 01/18] Translate 'Ninja code' article.md --- 1-js/03-code-quality/04-ninja-code/article.md | 226 +++++++++--------- 1 file changed, 113 insertions(+), 113 deletions(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index 19bb8f452..bd3c8deeb 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -1,241 +1,241 @@ -# Ninja code +# Código ninja -```quote author="Confucius (Analects)" -Learning without thought is labor lost; thought without learning is perilous. +```quote author="Confúcio" +Estudo sem pensamento é trabalho perdido; pensamento sem estudo é perigoso. ``` -Programmer ninjas of the past used these tricks to sharpen the mind of code maintainers. +Programadores ninjas do passado usavam truques para moldar a mente dos mantenedores de códigos. -Code review gurus look for them in test tasks. +Os gurus da revisão de código procuram por essas artimanhas em testes avaliativos. -Novice developers sometimes use them even better than programmer ninjas. +Desenvolvedores iniciantes muitas vezes usam essas habilidades até mesmo melhor que os programadores ninjas. -Read them carefully and find out who you are -- a ninja, a novice, or maybe a code reviewer? +Leia tudo com atenção e descubra quem é você -- um ninja, um iniciante ou um revisor de código? -```warn header="Irony detected" -Many try to follow ninja paths. Few succeed. +```warn header="Ironia detectada" +Muitos tentam ir pelo caminho dos ninjas. Poucos conseguem. ``` -## Brevity is the soul of wit +## Brevidade é a alma da perspicácia -Make the code as short as possible. Show how smart you are. +Faça o código o mais curto possível. Mostre quão inteligente você é. -Let subtle language features guide you. +Deixe a linguagem implícita guiar você. -For instance, take a look at this ternary operator `'?'`: +Por exemplo, dê uma olhada neste operador ternário `'?'`: ```js -// taken from a well-known javascript library +// tirado de uma bem conhecida biblioteca javascript i = i ? i < 0 ? Math.max(0, len + i) : i : 0; ``` -Cool, right? If you write like that, a developer who comes across this line and tries to understand what is the value of `i` is going to have a merry time. Then come to you, seeking for an answer. +Lega, né? Se você escrever dessa forma, um desenvolvedor que passar por essa linha e tentar entender qual o valor de `i` irá gastar um bom tempo. E então irá até você pedindo uma resposta. -Tell them that shorter is always better. Initiate them into the paths of ninja. +Diga a eles que o curto é sempre melhor. Introduza eles ao caminho do ninja. -## One-letter variables +## Variáveis de letra única -```quote author="Laozi (Tao Te Ching)" -The Dao hides in wordlessness. Only the Dao is well begun and well -completed. +```quote author="Lao Zi (Tao Te Ching)" +O Caminho é invisível e não tem nome. +Assim, apenas o Caminho é bom em auxiliar e concluir. ``` -Another way to code shorter is to use single-letter variable names everywhere. Like `a`, `b` or `c`. +Outra forma de escrever código mais rápido é usar nomes de variáveis de letra única em todo lugar. Como `a`, `b`, ou `c`. -A short variable disappears in the code like a real ninja in the forest. No one will be able to find it using "search" of the editor. And even if someone does, they won't be able to "decipher" what the name `a` or `b` means. +Uma variável curta desaparece no código como um ninja de verdade desaparece na floresta. Ninguém conseguirá encontrar ela usando a ferramenta de pesquisa do editor. E mesmo se alguém o fizer, não será capaz de decifrar o que o nome `a` ou `b` significam. -...But there's an exception. A real ninja will never use `i` as the counter in a `"for"` loop. Anywhere, but not here. Look around, there are many more exotic letters. For instance, `x` or `y`. +...Mas há uma exceção. Um ninja de verdade nunca usa `i` como o contador de um loop `for`. Em qualquer lugar, menos aqui. Veja em sua volta, existem várias outras letras exóticas. Por exemplo, `x` ou `y`. -An exotic variable as a loop counter is especially cool if the loop body takes 1-2 pages (make it longer if you can). Then if someone looks deep inside the loop, they won't be able to quickly figure out that the variable named `x` is the loop counter. +Uma variável exótica como um contador de loop é especialmente legal se o corpo do loop tiver uma ou duas páginas (faça ele bem longo se puder). Então se alguma pessoa der uma olhada dentro do loop, ela não será capaz de entender logo que aquela variável nomeada como `x` é simplesmente o contador do loop. -## Use abbreviations +## Use abreviações -If the team rules forbid the use of one-letter and vague names -- shorten them, make abbreviations. +Se as regras do time proibem o uso de variáveis de letra única e nomes vagos -- encurte elas, faça abreviações. -Like this: +Tipo assim: - `list` -> `lst`. - `userAgent` -> `ua`. - `browser` -> `brsr`. - ...etc -Only the one with truly good intuition will be able to understand such names. Try to shorten everything. Only a worthy person should be able to uphold the development of your code. +Apenas aquele com uma intuição bem aguçada terá a capacidade de entender esses nomes. Tente encurtar tudo. Apenas uma pessoa dígna será capaz de manter o desenvolvimento do seu código. -## Soar high. Be abstract. +## Voe alto. Seja abstrato. -```quote author="Laozi (Tao Te Ching)" -The great square is cornerless
-The great vessel is last complete,
-The great note is rarified sound,
-The great image has no form. +```quote author="Lao Zi (Tao Te Ching)" +O grande quadrado não tem ângulos
+O grande recipiente conclui-se tarde
+O grande som carece de ruído
+A grande imagem não tem forma. ``` -While choosing a name try to use the most abstract word. Like `obj`, `data`, `value`, `item`, `elem` and so on. +Ao escolher um nome tente usar a palavra mais abstrata possível. Como `obj`, `dado`, `valor`, `item`, `elem` e assim por diante. -- **The ideal name for a variable is `data`.** Use it everywhere you can. Indeed, every variable holds *data*, right? +- **O nome ideal para uma variável é `dado`.** Use ele em todo lugar que você puder. Aliás, toda variável armazena um *dado*, né? - ...But what to do if `data` is already taken? Try `value`, it's also universal. After all, a variable eventually gets a *value*. + ...Mas o que fazer se `dado` já foi usado? Tente `valor`, também é universal. No fim das contas, uma variável eventualmente terá um *valor*. -- **Name a variable by its type: `str`, `num`...** +- **Nomeie uma variável pelo seu tipo: `str`, `num`...** - Give them a try. A young initiate may wonder -- are such names really useful for a ninja? Indeed, they are! + Experimente isso. Um jovem pupilo deve pensar -- esses nomes são realmente úteis para um ninja? Bem, eles são! - Sure, the variable name still means something. It says what's inside the variable: a string, a number or something else. But when an outsider tries to understand the code, they'll be surprised to see that there's actually no information at all! And will ultimately fail to alter your well-thought code. + É óbvio, o nome da variável continua significando alguma coisa. Ele diz o que tem dentro da variável: uma string, um número ou qualquer outra coisa. Mas quando um forasteiro tentar entender o código, ele ficará surpreso ao ver que ali na verdade não existe nenhuma informação! E irá falhar ao tentar alterar seu código que foi escrito friamente calculado. - The value type is easy to find out by debugging. But what's the meaning of the variable? Which string/number does it store? + O tipo de uma variável é muito fácil de encontrar usando o debug. Mas qual é o real significado da variável? Que string/número ela armazena? - There's just no way to figure out without a good meditation! + Não existe nenhuma outra forma de descobrir isso sem uma boa meditaçao! -- **...But what if there are no more such names?** Just add a number: `data1, item2, elem5`... +- **...Mas e se não há mais nenhum desses nomes disponíveis?** Simplesmente adicione números: `dado1, item2, elem5`... -## Attention test +## Teste de perspicácia -Only a truly attentive programmer should be able to understand your code. But how to check that? +Apenas um programador perspicaz será capaz de entender o seu código. Mas como testar isso? -**One of the ways -- use similar variable names, like `date` and `data`.** +**Uma das formas -- use nomes similares para variáveis como `dado` e `data`.** -Mix them where you can. +Misture onde você puder. -A quick read of such code becomes impossible. And when there's a typo... Ummm... We're stuck for long, time to drink tea. +Uma leitura rápida no código se torna impossível. E quando temos um erro de digitação... Hummm... Ficaremos preso por um bom tempo, hora do chá. -## Smart synonyms +## Sinônimos inteligentes -```quote author="Laozi (Tao Te Ching)" -The Tao that can be told is not the eternal Tao. The name that can be named is not the eternal name. +```quote author="Confúcio" +A coisa mais difícil do mundo é encontrar um gato preto numa sala escura, especialmente se não existir um gato. ``` -Using *similar* names for *same* things makes life more interesting and shows your creativity to the public. +Usando nomes *similares* para as *mesmas* coisas faz da vida mais interessante e expõe a sua criatividade para o público. -For instance, consider function prefixes. If a function shows a message on the screen -- start it with `display…`, like `displayMessage`. And then if another function shows on the screen something else, like a user name, start it with `show…` (like `showName`). +Por exemplo, considere o prefixo de funções. Se uma função mostra uma mensagem na tela -- começe ela com `mostra...`, como `mostraMensagem`. E se outra função mostra na tela alguma outra coisa, como o nome de um usário, começe com `exibe...` (como `exibeNome`). -Insinuate that there's a subtle difference between such functions, while there is none. +Insinue que há uma pequena diferença entre as duas funções, quando na verdade não há. -Make a pact with fellow ninjas of the team: if John starts "showing" functions with `display...` in his code, then Peter could use `render..`, and Ann -- `paint...`. Note how much more interesting and diverse the code became. +Faça um pacto com seus parceiros ninjas do time: se João inicia funções de "exibir" com `mostra...` no código dele, então Pedro pode usar `renderiza...`, e Ana -- `imprime...`. Note como o código se torna bem mais interessante e diverso. -...And now the hat trick! +...Agora o pulo do gato! -For two functions with important differences -- use the same prefix! +Para duas funções com diferenças consideráveis -- use o mesmo prefixo! -For instance, the function `printPage(page)` will use a printer. And the function `printText(text)` will put the text on-screen. Let an unfamiliar reader think well over similarly named function `printMessage`: "Where does it put the message? To a printer or on the screen?". To make it really shine, `printMessage(message)` should output it in the new window! +Por exemplo, a função `imprimePagina(pagina)` vai usar a impressora. E a função `imprimeTexto(texto)` vai mostrar o texto na tela. Deixe um leitor não familiarizado refletir sobre a função com nome similar `imprimeMensagem`: "Onde isso vai pôr a mensagem? Na impressora ou na tela?". Para ficar ainda mais brilhante, `imprimeMensage(mensagem)` deveria mostrar sua saída numa nova janela! -## Reuse names +## Reuse nomes -```quote author="Laozi (Tao Te Ching)" -Once the whole is divided, the parts
-need names.
-There are already enough names.
-One must know when to stop. +```quote author="Lao Zi (Tao Te Ching)" +Mas quando ocorre a limitação +Logo surgem os nomes. +Quando os nomes surgem +Deve-se então saber parar. ``` -Add a new variable only when absolutely necessary. +Adicione uma variável nova apenas quando for absolutamente necessário. -Instead, reuse existing names. Just write new values into them. +Ao invés disso, reuse os nomes já existentes. Apenas atribua novos valores para eles. -In a function try to use only variables passed as parameters. +Em uma função tente usar apenas as funções usadas como parâmetros. -That would make it really hard to identify what's exactly in the variable *now*. And also where it comes from. A person with weak intuition would have to analyze the code line-by-line and track the changes through every code branch. +Isso fará com que seja bem mais difícil identificar o que exatamente está dentro da variável *agora*. E também de onde ela vem. Uma pessoa com intuição fraca terá que analisar o código linha por linha e observar as mudanças através de cada parte do código. -**An advanced variant of the approach is to covertly (!) replace the value with something alike in the middle of a loop or a function.** +**Uma variação avançada dessa abordagem é substituir secretamente (!) o valor da variável com algo semelhante no meio do loop ou de uma função.** -For instance: +Por exemplo: ```js -function ninjaFunction(elem) { - // 20 lines of code working with elem +function funcaoNinja(elem) { + // 20 linhas de código trabalhando com elem elem = clone(elem); - // 20 more lines, now working with the clone of the elem! + // mais 20 linhas, agora trabalhando com o clone de elem! } ``` -A fellow programmer who wants to work with `elem` in the second half of the function will be surprised... Only during the debugging, after examining the code they will find out that they're working with a clone! +Um colega programador que quiser trabalhar com `elem` será surpreendido na segunda metade da função... Somente durante o debug, depois de um exame do código, ele irá descobrir que estava trabalhando com um clone! -Seen in code regularly. Deadly effective even against an experienced ninja. +Isso é visto frequentemente em códigos. Mortalmente efetivo até mesmo com os ninjas mais experientes. -## Underscores for fun +## Sublinhas por diversão -Put underscores `_` and `__` before variable names. Like `_name` or `__value`. It would be great if only you knew their meaning. Or, better, add them just for fun, without particular meaning at all. Or different meanings in different places. +Coloque sublinhas `_` e `__` antes dos nomes das variáveis. Como `_nome` ou `__valor`. Será melhor ainda se apenas você souber o significado disso. Ou, melhor, adicione apenas por diversão, sem um signifcado em particular. Ou significados diferentes em lugares diferentes. -You kill two rabbits with one shot. First, the code becomes longer and less readable, and the second, a fellow developer may spend a long time trying to figure out what the underscores mean. +Você mata dois coelhos numa paulada só. Primeiro, o código se torna mais longo e menos legível, e segundo, um colega desenvolvedor terá que gastar um bom tempo tentando entender o que significam as sublinhas. -A smart ninja puts underscores at one spot of code and evades them at other places. That makes the code even more fragile and increases the probability of future errors. +Um ninja inteligente põe sublinhas em uma parte do código e evita elas em outras partes. Isso deixa o código ainda mais frágil e aumentam as chances de futuros erros. -## Show your love +## Mostre seu amor -Let everyone see how magnificent your entities are! Names like `superElement`, `megaFrame` and `niceItem` will definitely enlighten a reader. +Faça com que todos vejam a grandiosidade das suas entidades! Nomes como `superElemento`, `megaFrame` e `itemLegal` com certeza irão deixar isso bem claro para o leitor. -Indeed, from one hand, something is written: `super..`, `mega..`, `nice..` But from the other hand -- that brings no details. A reader may decide to look for a hidden meaning and meditate for an hour or two. +Aliás, por um lado, algo é escrito como: `super..`, `mega..`, `legal..` Mas por outro -- isso não traz detalhe nenhum. Um leitor talvez decida procurar por um signifcado e irá meditar por uma hora ou duas. -## Overlap outer variables +## Sobreponha variáveis externas ```quote author="Guan Yin Zi" -When in the light, can't see anything in the darkness.
-When in the darkness, can see everything in the light. +Quando na luz, não podes ver nada na escuridão. +Quando na escuridão, não podes ver nada na luz. ``` -Use same names for variables inside and outside a function. As simple. No efforts required. +Use os mesmos nomes para variáveis dentro e fora de uma função. Bem simples. Sem esforço. ```js -let *!*user*/!* = authenticateUser(); +let *!*usuario*/!* = autenticaUsuario(); function render() { - let *!*user*/!* = anotherValue(); + let *!*usuario*/!* = outroValor(); ... - ...many lines... + ...muitas linhas... ... - ... // <-- a programmer wants to work with user here and... + ... // <-- um programador vai querer trabalhar com usuario aqui e... ... } ``` -A programmer who jumps inside the `render` will probably fail to notice that there's a local `user` shadowing the outer one. +Um programador que olhar dentro de `render` provavelmente vai falhar em notar que já existe um `usuario` local substituindo a variável exterior à função. -Then they'll try to work with `user` assuming that it's the external variable, the result of `authenticateUser()`... The trap is sprung! Hello, debugger... +Então ele vai tentar trabalhar com `usuario` assumindo que é a variável exterior, o resultado de `autenticaUsuario()`... A armadilha tá feita! Olá, debugger... -## Side-effects everywhere! +## Efeitos colaterais em todo lugar! -There are functions that look like they don't change anything. Like `isReady()`, `checkPermission()`, `findTags()`... They are assumed to carry out calculations, find and return the data, without changing anything outside of them. In other words, without "side-effects". +Existem funções que parecem que não alteram nada. Como `estaPronto()`, `checaPermissao()`, `encontraTags()`... Elas são feitas para realizar cálculos, encontrar e retornar o dado, sem mudar nada fora delas. Em outras palavras, sem "efeito colateral". -**A really beautiful trick is to add a "useful" action to them, besides the main task.** +**Um truque ótimo é adicionar uma ação "útil" a elas, além da sua tarefa principal.** -An expression of dazed surprise on the face of your colleague when they see a function named `is..`, `check..` or `find...` changing something -- will definitely broaden your boundaries of reason. +Uma expressão de surpresa atordoada na cara dos seus colegas quando eles virem uma função com nome `esta...`, `checa...` ou `encontra...` mudando alguma coisa -- vai definitivamente ampliar seus limites da razão. -**Another way to surprise is to return a non-standard result.** +**Uma outra forma de surpreender é retornar um valor não padrão.** -Show your original thinking! Let the call of `checkPermission` return not `true/false`, but a complex object with the results of the check. +Mostre o que é pensar fora da caixa! Faça com que a chamada de `checaPermissao` retorne não um `true/false`, mas sim um complexo objeto com o resultado da checagem. -Those developers who try to write `if (checkPermission(..))`, will wonder why it doesn't work. Tell them: "Read the docs!". And give this article. +Aqueles desenvolvedores que tentarem escrever `if (checaPermissao(..))`, vai se perguntar por que não funciona. Diga a eles: "Leia a documentação!". E mostre este artigo. -## Powerful functions! +## Funções superpoderosas! -```quote author="Laozi (Tao Te Ching)" -The great Tao flows everywhere,
-both to the left and to the right. +```quote author="Lao Zi (Tao Te Ching)" +O Grande Caminho é vasto +Pode ser encontrado na esquerda e na direita ``` -Don't limit the function by what's written in its name. Be broader. +Não limite a função pelo o que está escrito em seu nome. Seja amplo. -For instance, a function `validateEmail(email)` could (besides checking the email for correctness) show an error message and ask to re-enter the email. +Por exemplo, uma função `validaEmail(email)` poderia (além de checar a validade do email) mostrar uma mensagem de erro e perguntar para reescrever o email. -Additional actions should not be obvious from the function name. A true ninja coder will make them not obvious from the code as well. +Açoes adicionais não devem ser óbvias pelo nome da função. Um verdadeiro programador ninja também as tornará não óbvias assim como o resto do código. -**Joining several actions into one protects your code from reuse.** +**Juntar várias ações em uma protegerá seu código de ser reutilizado.** -Imagine, another developer wants only to check the email, and not output any message. Your function `validateEmail(email)` that does both will not suit them. So they won't break your meditation by asking anything about it. +Imagine, algum outro desenvolvedor quer apenas checar o email, mas não mostrar uma mensagem. Sua função `validaEmail(email)` que executa as duas ações não servirá pra ele. Então ele não irá interromper sua meditação perguntando sobre ela. -## Summary +## Sumário -All "pieces of advice" above are from the real code... Sometimes, written by experienced developers. Maybe even more experienced than you are ;) +Todas as "peças de conselhos" acima são de códigos reais... Algumas escritas por desenvolvedores experientes. Talvez até mais experientes do que você ;) -- Follow some of them, and your code will become full of surprises. -- Follow many of them, and your code will become truly yours, no one would want to change it. -- Follow all, and your code will become a valuable lesson for young developers looking for enlightenment. +- Siga algumas delas, e seu código se tornará cheio de surpresas. +- Siga muitas delas, e seu código se tornará realmente seu, ninguém irá querer alterá-lo. +- Siga todas, e seu código se tornará uma lição valiosa para novos desenvolvedores procurando pela iluminação. From 4a67602dd16d0b4e94417767290b1b4a6f2e4174 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:05:18 -0300 Subject: [PATCH 02/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index bd3c8deeb..25bfc75f8 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -1,7 +1,7 @@ # Código ninja -```quote author="Confúcio" +```quote author="Confúcio (Analects)" Estudo sem pensamento é trabalho perdido; pensamento sem estudo é perigoso. ``` From e6054242137ce1ab37cdf77080b55df5452fa5be Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:05:46 -0300 Subject: [PATCH 03/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index 25bfc75f8..6bdae588f 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -5,7 +5,7 @@ Estudo sem pensamento é trabalho perdido; pensamento sem estudo é perigoso. ``` -Programadores ninjas do passado usavam truques para moldar a mente dos mantenedores de códigos. +Programadores ninjas do passado usavam estes truques para moldar a mente dos mantenedores de código. Os gurus da revisão de código procuram por essas artimanhas em testes avaliativos. From 9323881e78726c3aa728328cf66d286bc6aa3758 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:06:00 -0300 Subject: [PATCH 04/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index 6bdae588f..e77730fcd 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -32,7 +32,7 @@ Por exemplo, dê uma olhada neste operador ternário `'?'`: i = i ? i < 0 ? Math.max(0, len + i) : i : 0; ``` -Lega, né? Se você escrever dessa forma, um desenvolvedor que passar por essa linha e tentar entender qual o valor de `i` irá gastar um bom tempo. E então irá até você pedindo uma resposta. +Legal, né? Se você escrever dessa forma, um desenvolvedor que passar por essa linha e tentar entender qual o valor de `i` irá gastar um bom tempo. E então irá até você pedindo uma resposta. Diga a eles que o curto é sempre melhor. Introduza eles ao caminho do ninja. From 476e7cfef5a6d9f9027c00089629a12252d6d4e3 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:06:17 -0300 Subject: [PATCH 05/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index e77730fcd..ee7dbbf01 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -34,7 +34,7 @@ i = i ? i < 0 ? Math.max(0, len + i) : i : 0; Legal, né? Se você escrever dessa forma, um desenvolvedor que passar por essa linha e tentar entender qual o valor de `i` irá gastar um bom tempo. E então irá até você pedindo uma resposta. -Diga a eles que o curto é sempre melhor. Introduza eles ao caminho do ninja. +Diga a eles que o curto é sempre melhor. Introduza eles no caminho do ninja. ## Variáveis de letra única From e9322417a4e635f114d107b897d8e2ae39d18306 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:06:27 -0300 Subject: [PATCH 06/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index ee7dbbf01..08bbef17e 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -36,7 +36,7 @@ Legal, né? Se você escrever dessa forma, um desenvolvedor que passar por essa Diga a eles que o curto é sempre melhor. Introduza eles no caminho do ninja. -## Variáveis de letra única +## Variáveis de uma letra ```quote author="Lao Zi (Tao Te Ching)" O Caminho é invisível e não tem nome. From f0c8f5ce3b53cd640c5f88c752ae7fe942856bfe Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:09:02 -0300 Subject: [PATCH 07/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index 08bbef17e..ca1368d09 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -2,7 +2,7 @@ ```quote author="Confúcio (Analects)" -Estudo sem pensamento é trabalho perdido; pensamento sem estudo é perigoso. +Aprender sem pensar é trabalho perdido; pensar sem aprender é perigoso. ``` Programadores ninjas do passado usavam estes truques para moldar a mente dos mantenedores de código. From aa4b3c7c16195473dbdea91eb1a0a889d1b53619 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:10:21 -0300 Subject: [PATCH 08/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index ca1368d09..ac7c10512 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -177,7 +177,7 @@ Aliás, por um lado, algo é escrito como: `super..`, `mega..`, `legal..` Mas po ```quote author="Guan Yin Zi" Quando na luz, não podes ver nada na escuridão. -Quando na escuridão, não podes ver nada na luz. +Quando na escuridão, pode ver tudo na luz. ``` Use os mesmos nomes para variáveis dentro e fora de uma função. Bem simples. Sem esforço. From 9854a497358508e8c0289278d519fd0eabaadca5 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:10:57 -0300 Subject: [PATCH 09/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index ac7c10512..d161d2d36 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -176,7 +176,7 @@ Aliás, por um lado, algo é escrito como: `super..`, `mega..`, `legal..` Mas po ## Sobreponha variáveis externas ```quote author="Guan Yin Zi" -Quando na luz, não podes ver nada na escuridão. +Quando na luz, não pode ver nada na escuridão.
Quando na escuridão, pode ver tudo na luz. ``` From 88fa30d96c1a52b3f779434d67b15d7813529499 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:11:52 -0300 Subject: [PATCH 10/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index d161d2d36..9baa1f393 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -43,7 +43,7 @@ O Caminho é invisível e não tem nome. Assim, apenas o Caminho é bom em auxiliar e concluir. ``` -Outra forma de escrever código mais rápido é usar nomes de variáveis de letra única em todo lugar. Como `a`, `b`, ou `c`. +Outra forma de escrever código mais curto é usar nomes de variáveis com uma única letra em todo lugar. Como `a`, `b`, ou `c`. Uma variável curta desaparece no código como um ninja de verdade desaparece na floresta. Ninguém conseguirá encontrar ela usando a ferramenta de pesquisa do editor. E mesmo se alguém o fizer, não será capaz de decifrar o que o nome `a` ou `b` significam. From 5af2740eb628644e0c0188af670aef4f73b45d13 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:12:39 -0300 Subject: [PATCH 11/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index 9baa1f393..302b065ef 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -218,7 +218,7 @@ Aqueles desenvolvedores que tentarem escrever `if (checaPermissao(..))`, vai se ## Funções superpoderosas! ```quote author="Lao Zi (Tao Te Ching)" -O Grande Caminho é vasto +O grande Tao flui por toda parte,
Pode ser encontrado na esquerda e na direita ``` From 0871d98b6124fa137797e6a2c7f826f0856a26e3 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:13:23 -0300 Subject: [PATCH 12/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index 302b065ef..c4991d970 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -39,7 +39,8 @@ Diga a eles que o curto é sempre melhor. Introduza eles no caminho do ninja. ## Variáveis de uma letra ```quote author="Lao Zi (Tao Te Ching)" -O Caminho é invisível e não tem nome. +O Dao se esconde na ausência de palavras. Apenas o Dao está bem iniciado e bem +concluído. Assim, apenas o Caminho é bom em auxiliar e concluir. ``` From 08afe411f3603177cde3815766ce84f692fac396 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:14:52 -0300 Subject: [PATCH 13/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index c4991d970..ce59171f7 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -50,7 +50,7 @@ Uma variável curta desaparece no código como um ninja de verdade desaparece na ...Mas há uma exceção. Um ninja de verdade nunca usa `i` como o contador de um loop `for`. Em qualquer lugar, menos aqui. Veja em sua volta, existem várias outras letras exóticas. Por exemplo, `x` ou `y`. -Uma variável exótica como um contador de loop é especialmente legal se o corpo do loop tiver uma ou duas páginas (faça ele bem longo se puder). Então se alguma pessoa der uma olhada dentro do loop, ela não será capaz de entender logo que aquela variável nomeada como `x` é simplesmente o contador do loop. +Uma variável exótica como um contador de loop é especialmente legal se o corpo do loop tiver uma ou duas páginas (faça ele mais longo se puder). Então se alguma pessoa der uma olhada dentro do loop, ela não será capaz de entender logo que aquela variável nomeada como `x` é simplesmente o contador do loop. ## Use abreviações From 63b59a63a8b0de5ddf98b412af653572f62a6e51 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:15:54 -0300 Subject: [PATCH 14/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index ce59171f7..e77891bb9 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -106,7 +106,7 @@ Uma leitura rápida no código se torna impossível. E quando temos um erro de d ## Sinônimos inteligentes ```quote author="Confúcio" -A coisa mais difícil do mundo é encontrar um gato preto numa sala escura, especialmente se não existir um gato. +O Tao que pode ser narrado não é o Tao eterno. O nome que pode ser nomeado não é o nome eterno. ``` Usando nomes *similares* para as *mesmas* coisas faz da vida mais interessante e expõe a sua criatividade para o público. From 3a8a1505b521ed92c79e232c2a1812c8cc58a948 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:16:37 -0300 Subject: [PATCH 15/18] Update 1-js/03-code-quality/04-ninja-code/article.md Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index e77891bb9..76b89a1c5 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -220,7 +220,7 @@ Aqueles desenvolvedores que tentarem escrever `if (checaPermissao(..))`, vai se ```quote author="Lao Zi (Tao Te Ching)" O grande Tao flui por toda parte,
-Pode ser encontrado na esquerda e na direita +tanto para a esquerda quanto para a direita. ``` Não limite a função pelo o que está escrito em seu nome. Seja amplo. From 205e87f068323b9d7f2304b9fddd1a1f96cc16af Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 10:25:14 -0300 Subject: [PATCH 16/18] Apply suggestions from code review Co-authored-by: Osvaldo Dias dos Santos --- 1-js/03-code-quality/04-ninja-code/article.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index 76b89a1c5..3b34f3814 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -105,7 +105,7 @@ Uma leitura rápida no código se torna impossível. E quando temos um erro de d ## Sinônimos inteligentes -```quote author="Confúcio" +```quote author="Lao Zi (Tao Te Ching)" O Tao que pode ser narrado não é o Tao eterno. O nome que pode ser nomeado não é o nome eterno. ``` @@ -126,9 +126,9 @@ Por exemplo, a função `imprimePagina(pagina)` vai usar a impressora. E a funç ## Reuse nomes ```quote author="Lao Zi (Tao Te Ching)" -Mas quando ocorre a limitação -Logo surgem os nomes. -Quando os nomes surgem +Uma vez o todo dividido, as partes
+precisam de nomes.
+Já existem nomes suficientes.
Deve-se então saber parar. ``` @@ -136,7 +136,7 @@ Adicione uma variável nova apenas quando for absolutamente necessário. Ao invés disso, reuse os nomes já existentes. Apenas atribua novos valores para eles. -Em uma função tente usar apenas as funções usadas como parâmetros. +Em uma função tente apenas usar variáveis passadas como parâmetros. Isso fará com que seja bem mais difícil identificar o que exatamente está dentro da variável *agora*. E também de onde ela vem. Uma pessoa com intuição fraca terá que analisar o código linha por linha e observar as mudanças através de cada parte do código. @@ -156,21 +156,21 @@ function funcaoNinja(elem) { Um colega programador que quiser trabalhar com `elem` será surpreendido na segunda metade da função... Somente durante o debug, depois de um exame do código, ele irá descobrir que estava trabalhando com um clone! -Isso é visto frequentemente em códigos. Mortalmente efetivo até mesmo com os ninjas mais experientes. +Isso é visto frequentemente em códigos. Mortalmente efetivo até mesmo contra os ninjas mais experientes. ## Sublinhas por diversão -Coloque sublinhas `_` e `__` antes dos nomes das variáveis. Como `_nome` ou `__valor`. Será melhor ainda se apenas você souber o significado disso. Ou, melhor, adicione apenas por diversão, sem um signifcado em particular. Ou significados diferentes em lugares diferentes. +Coloque sublinhas `_` e `__` antes dos nomes das variáveis. Como `_nome` ou `__valor`. Seria melhor ainda se apenas você soubesse o significado disso. Ou, melhor, adicione apenas por diversão, sem um signifcado em particular. Ou significados diferentes em lugares diferentes. -Você mata dois coelhos numa paulada só. Primeiro, o código se torna mais longo e menos legível, e segundo, um colega desenvolvedor terá que gastar um bom tempo tentando entender o que significam as sublinhas. +Você mata dois coelhos numa paulada só. Primeiro, o código se torna mais longo e menos legível, e segundo, um colega desenvolvedor pode gastar um bom tempo tentando entender o que significam as sublinhas. -Um ninja inteligente põe sublinhas em uma parte do código e evita elas em outras partes. Isso deixa o código ainda mais frágil e aumentam as chances de futuros erros. +Um ninja inteligente põe sublinhas em uma parte do código e evita elas em outras partes. Isso deixa o código ainda mais frágil e aumenta as chances de futuros erros. ## Mostre seu amor -Faça com que todos vejam a grandiosidade das suas entidades! Nomes como `superElemento`, `megaFrame` e `itemLegal` com certeza irão deixar isso bem claro para o leitor. +Faça com que todos vejam a grandiosidade das suas entidades! Nomes como `superElemento`, `megaFrame` e `itemLegal` com certeza irão iluminar um leitor. -Aliás, por um lado, algo é escrito como: `super..`, `mega..`, `legal..` Mas por outro -- isso não traz detalhe nenhum. Um leitor talvez decida procurar por um signifcado e irá meditar por uma hora ou duas. +Aliás, por um lado, algo é escrito como: `super..`, `mega..`, `legal..` Mas por outro -- isso não traz detalhe nenhum. Um leitor talvez decida procurar por um signifcado oculto e meditar por uma hora ou duas. @@ -207,7 +207,7 @@ Existem funções que parecem que não alteram nada. Como `estaPronto()`, `checa **Um truque ótimo é adicionar uma ação "útil" a elas, além da sua tarefa principal.** -Uma expressão de surpresa atordoada na cara dos seus colegas quando eles virem uma função com nome `esta...`, `checa...` ou `encontra...` mudando alguma coisa -- vai definitivamente ampliar seus limites da razão. +Uma expressão de surpresa atordoada na cara dos seus colegas quando eles virem uma função com nome `é...`, `checa...` ou `encontra...` mudando alguma coisa -- vai definitivamente ampliar seus limites da razão. **Uma outra forma de surpreender é retornar um valor não padrão.** @@ -223,20 +223,20 @@ O grande Tao flui por toda parte,
tanto para a esquerda quanto para a direita. ``` -Não limite a função pelo o que está escrito em seu nome. Seja amplo. +Não limite a função pelo que está escrito em seu nome. Seja amplo. -Por exemplo, uma função `validaEmail(email)` poderia (além de checar a validade do email) mostrar uma mensagem de erro e perguntar para reescrever o email. +Por exemplo, uma função `validaEmail(email)` poderia (além de checar a validade do email) mostrar uma mensagem de erro e pedir para re-entrar o email. Açoes adicionais não devem ser óbvias pelo nome da função. Um verdadeiro programador ninja também as tornará não óbvias assim como o resto do código. **Juntar várias ações em uma protegerá seu código de ser reutilizado.** -Imagine, algum outro desenvolvedor quer apenas checar o email, mas não mostrar uma mensagem. Sua função `validaEmail(email)` que executa as duas ações não servirá pra ele. Então ele não irá interromper sua meditação perguntando sobre ela. +Imagine, algum outro desenvolvedor quer apenas checar o email, mas não mostrar uma mensagem. Sua função `validaEmail(email)` que executa as duas ações não servirá pra ele. Assim, ele não irá interromper a sua meditação perguntando algo sobre ela. ## Sumário -Todas as "peças de conselhos" acima são de códigos reais... Algumas escritas por desenvolvedores experientes. Talvez até mais experientes do que você ;) +Todas as "peças de conselho" acima são de códigos reais... Algumas escritas por desenvolvedores experientes. Talvez até mais experientes do que você ;) - Siga algumas delas, e seu código se tornará cheio de surpresas. - Siga muitas delas, e seu código se tornará realmente seu, ninguém irá querer alterá-lo. -- Siga todas, e seu código se tornará uma lição valiosa para novos desenvolvedores procurando pela iluminação. +- Siga todas, e seu código se tornará numa lição valiosa para novos desenvolvedores procurando pela iluminação. From 1320994eac13207bca9932d6b0d92a388ca01776 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 11:39:39 -0300 Subject: [PATCH 17/18] Apply suggestions from code review --- 1-js/03-code-quality/04-ninja-code/article.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index 3b34f3814..b2d9c0157 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -145,7 +145,7 @@ Isso fará com que seja bem mais difícil identificar o que exatamente está den Por exemplo: ```js -function funcaoNinja(elem) { +function ninjaFunction(elem) { // 20 linhas de código trabalhando com elem elem = clone(elem); @@ -170,7 +170,7 @@ Um ninja inteligente põe sublinhas em uma parte do código e evita elas em outr Faça com que todos vejam a grandiosidade das suas entidades! Nomes como `superElemento`, `megaFrame` e `itemLegal` com certeza irão iluminar um leitor. -Aliás, por um lado, algo é escrito como: `super..`, `mega..`, `legal..` Mas por outro -- isso não traz detalhe nenhum. Um leitor talvez decida procurar por um signifcado oculto e meditar por uma hora ou duas. +Aliás, por um lado, algo é escrito como: `super..`, `mega..`, `nice..` Mas por outro -- isso não traz detalhe nenhum. Um leitor talvez decida procurar por um signifcado oculto e meditar por uma hora ou duas. @@ -184,10 +184,10 @@ Quando na escuridão, pode ver tudo na luz. Use os mesmos nomes para variáveis dentro e fora de uma função. Bem simples. Sem esforço. ```js -let *!*usuario*/!* = autenticaUsuario(); +let *!*user*/!* = autenticateUser(); function render() { - let *!*usuario*/!* = outroValor(); + let *!*user*/!* = anotherValue(); ... ...muitas linhas... ... @@ -196,22 +196,22 @@ function render() { } ``` -Um programador que olhar dentro de `render` provavelmente vai falhar em notar que já existe um `usuario` local substituindo a variável exterior à função. +Um programador que olhar dentro de `render` provavelmente vai falhar em notar que já existe um `user` local substituindo a variável exterior à função. -Então ele vai tentar trabalhar com `usuario` assumindo que é a variável exterior, o resultado de `autenticaUsuario()`... A armadilha tá feita! Olá, debugger... +Então ele vai tentar trabalhar com `user` assumindo que é a variável exterior, o resultado de `authenticateUser()`... A armadilha tá feita! Olá, debugger... ## Efeitos colaterais em todo lugar! -Existem funções que parecem que não alteram nada. Como `estaPronto()`, `checaPermissao()`, `encontraTags()`... Elas são feitas para realizar cálculos, encontrar e retornar o dado, sem mudar nada fora delas. Em outras palavras, sem "efeito colateral". +Existem funções que parecem que não alteram nada. Como `isReady()`, `checkPermission()`, `findTags()`... Elas são feitas para realizar cálculos, encontrar e retornar o dado, sem mudar nada fora delas. Em outras palavras, sem "efeito colateral". **Um truque ótimo é adicionar uma ação "útil" a elas, além da sua tarefa principal.** -Uma expressão de surpresa atordoada na cara dos seus colegas quando eles virem uma função com nome `é...`, `checa...` ou `encontra...` mudando alguma coisa -- vai definitivamente ampliar seus limites da razão. +Uma expressão de surpresa atordoada na cara dos seus colegas quando eles virem uma função com nome `is..`, `check..` ou `find..` mudando alguma coisa -- vai definitivamente ampliar seus limites da razão. **Uma outra forma de surpreender é retornar um valor não padrão.** -Mostre o que é pensar fora da caixa! Faça com que a chamada de `checaPermissao` retorne não um `true/false`, mas sim um complexo objeto com o resultado da checagem. +Mostre o que é pensar fora da caixa! Faça com que a chamada de `checkPermission` retorne não um `true/false`, mas sim um complexo objeto com o resultado da checagem. Aqueles desenvolvedores que tentarem escrever `if (checaPermissao(..))`, vai se perguntar por que não funciona. Diga a eles: "Leia a documentação!". E mostre este artigo. From dc699c0607c9c38634efc608d8825e97d4b9bd25 Mon Sep 17 00:00:00 2001 From: Gabriel Fernandes Date: Wed, 3 Dec 2025 11:42:02 -0300 Subject: [PATCH 18/18] Apply suggestions from code review --- 1-js/03-code-quality/04-ninja-code/article.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/1-js/03-code-quality/04-ninja-code/article.md b/1-js/03-code-quality/04-ninja-code/article.md index b2d9c0157..02af8516a 100644 --- a/1-js/03-code-quality/04-ninja-code/article.md +++ b/1-js/03-code-quality/04-ninja-code/article.md @@ -48,7 +48,7 @@ Outra forma de escrever código mais curto é usar nomes de variáveis com uma Uma variável curta desaparece no código como um ninja de verdade desaparece na floresta. Ninguém conseguirá encontrar ela usando a ferramenta de pesquisa do editor. E mesmo se alguém o fizer, não será capaz de decifrar o que o nome `a` ou `b` significam. -...Mas há uma exceção. Um ninja de verdade nunca usa `i` como o contador de um loop `for`. Em qualquer lugar, menos aqui. Veja em sua volta, existem várias outras letras exóticas. Por exemplo, `x` ou `y`. +...Mas há uma exceção. Um ninja de verdade nunca usa `i` como o contador de um loop `"for"`. Em qualquer lugar, menos aqui. Veja em sua volta, existem várias outras letras exóticas. Por exemplo, `x` ou `y`. Uma variável exótica como um contador de loop é especialmente legal se o corpo do loop tiver uma ou duas páginas (faça ele mais longo se puder). Então se alguma pessoa der uma olhada dentro do loop, ela não será capaz de entender logo que aquela variável nomeada como `x` é simplesmente o contador do loop. @@ -74,11 +74,11 @@ O grande som carece de ruído
A grande imagem não tem forma. ``` -Ao escolher um nome tente usar a palavra mais abstrata possível. Como `obj`, `dado`, `valor`, `item`, `elem` e assim por diante. +Ao escolher um nome tente usar a palavra mais abstrata possível. Como `obj`, `data`, `value`, `item`, `elem` e assim por diante. -- **O nome ideal para uma variável é `dado`.** Use ele em todo lugar que você puder. Aliás, toda variável armazena um *dado*, né? +- **O nome ideal para uma variável é `data`.** Use ele em todo lugar que você puder. Aliás, toda variável armazena um *dado*, né? - ...Mas o que fazer se `dado` já foi usado? Tente `valor`, também é universal. No fim das contas, uma variável eventualmente terá um *valor*. + ...Mas o que fazer se `data` já foi usado? Tente `value`, também é universal. No fim das contas, uma variável eventualmente terá um *valor*. - **Nomeie uma variável pelo seu tipo: `str`, `num`...** @@ -90,13 +90,13 @@ Ao escolher um nome tente usar a palavra mais abstrata possível. Como `obj`, `d Não existe nenhuma outra forma de descobrir isso sem uma boa meditaçao! -- **...Mas e se não há mais nenhum desses nomes disponíveis?** Simplesmente adicione números: `dado1, item2, elem5`... +- **...Mas e se não há mais nenhum desses nomes disponíveis?** Simplesmente adicione números: `data1, item2, elem5`... ## Teste de perspicácia Apenas um programador perspicaz será capaz de entender o seu código. Mas como testar isso? -**Uma das formas -- use nomes similares para variáveis como `dado` e `data`.** +**Uma das formas -- use nomes similares para variáveis como `date` e `data`.** Misture onde você puder. @@ -111,17 +111,17 @@ O Tao que pode ser narrado não é o Tao eterno. O nome que pode ser nomeado nã Usando nomes *similares* para as *mesmas* coisas faz da vida mais interessante e expõe a sua criatividade para o público. -Por exemplo, considere o prefixo de funções. Se uma função mostra uma mensagem na tela -- começe ela com `mostra...`, como `mostraMensagem`. E se outra função mostra na tela alguma outra coisa, como o nome de um usário, começe com `exibe...` (como `exibeNome`). +Por exemplo, considere o prefixo de funções. Se uma função mostra uma mensagem na tela -- começe ela com `display...`, como `displayMessage`. E se outra função mostra na tela alguma outra coisa, como o nome de um usuário, comece com `show...` (como `showName`). Insinue que há uma pequena diferença entre as duas funções, quando na verdade não há. -Faça um pacto com seus parceiros ninjas do time: se João inicia funções de "exibir" com `mostra...` no código dele, então Pedro pode usar `renderiza...`, e Ana -- `imprime...`. Note como o código se torna bem mais interessante e diverso. +Faça um pacto com seus parceiros ninjas do time: se João inicia funções de "exibir" com `display...` no código dele, então Pedro pode usar `render...`, e Ana -- `paint...`. Note como o código se torna bem mais interessante e diverso. ...Agora o pulo do gato! Para duas funções com diferenças consideráveis -- use o mesmo prefixo! -Por exemplo, a função `imprimePagina(pagina)` vai usar a impressora. E a função `imprimeTexto(texto)` vai mostrar o texto na tela. Deixe um leitor não familiarizado refletir sobre a função com nome similar `imprimeMensagem`: "Onde isso vai pôr a mensagem? Na impressora ou na tela?". Para ficar ainda mais brilhante, `imprimeMensage(mensagem)` deveria mostrar sua saída numa nova janela! +Por exemplo, a função `printPage(page)` vai usar a impressora. E a função `printText(text)` vai mostrar o texto na tela. Deixe um leitor não familiarizado refletir sobre a função com nome similar `printMessage`: "Onde isso vai pôr a mensagem? Na impressora ou na tela?". Para ficar ainda mais brilhante, `printMessage(message)` deveria mostrar sua saída numa nova janela! ## Reuse nomes @@ -168,7 +168,7 @@ Um ninja inteligente põe sublinhas em uma parte do código e evita elas em outr ## Mostre seu amor -Faça com que todos vejam a grandiosidade das suas entidades! Nomes como `superElemento`, `megaFrame` e `itemLegal` com certeza irão iluminar um leitor. +Faça com que todos vejam a grandiosidade das suas entidades! Nomes como `superElement`, `megaFrame` e `niceItem` com certeza irão iluminar um leitor. Aliás, por um lado, algo é escrito como: `super..`, `mega..`, `nice..` Mas por outro -- isso não traz detalhe nenhum. Um leitor talvez decida procurar por um signifcado oculto e meditar por uma hora ou duas. @@ -213,7 +213,7 @@ Uma expressão de surpresa atordoada na cara dos seus colegas quando eles virem Mostre o que é pensar fora da caixa! Faça com que a chamada de `checkPermission` retorne não um `true/false`, mas sim um complexo objeto com o resultado da checagem. -Aqueles desenvolvedores que tentarem escrever `if (checaPermissao(..))`, vai se perguntar por que não funciona. Diga a eles: "Leia a documentação!". E mostre este artigo. +Aqueles desenvolvedores que tentarem escrever `if (checkPermission(..))`, vai se perguntar por que não funciona. Diga a eles: "Leia a documentação!". E mostre este artigo. ## Funções superpoderosas! @@ -225,13 +225,13 @@ tanto para a esquerda quanto para a direita. Não limite a função pelo que está escrito em seu nome. Seja amplo. -Por exemplo, uma função `validaEmail(email)` poderia (além de checar a validade do email) mostrar uma mensagem de erro e pedir para re-entrar o email. +Por exemplo, uma função `validateEmail(email)` poderia (além de checar a validade do email) mostrar uma mensagem de erro e pedir para re-entrar o email. Açoes adicionais não devem ser óbvias pelo nome da função. Um verdadeiro programador ninja também as tornará não óbvias assim como o resto do código. **Juntar várias ações em uma protegerá seu código de ser reutilizado.** -Imagine, algum outro desenvolvedor quer apenas checar o email, mas não mostrar uma mensagem. Sua função `validaEmail(email)` que executa as duas ações não servirá pra ele. Assim, ele não irá interromper a sua meditação perguntando algo sobre ela. +Imagine, algum outro desenvolvedor quer apenas checar o email, mas não mostrar uma mensagem. Sua função `validateEmail(email)` que executa as duas ações não servirá pra ele. Assim, ele não irá interromper a sua meditação perguntando algo sobre ela. ## Sumário