From 70009621d0aa257dbc110e8040824dc0cce7361c Mon Sep 17 00:00:00 2001 From: Bruno Dulcetti Date: Tue, 5 Dec 2017 18:11:36 -0200 Subject: [PATCH 1/2] Whys * in brazilian portuguese, the why receive a circumflex accent when is alone inside the question --- a1/i18n/pt-BR.md | 236 +++++++++++++++++++++++------------------------ 1 file changed, 118 insertions(+), 118 deletions(-) diff --git a/a1/i18n/pt-BR.md b/a1/i18n/pt-BR.md index 2c5d8fb5..a57876ef 100644 --- a/a1/i18n/pt-BR.md +++ b/a1/i18n/pt-BR.md @@ -115,9 +115,9 @@ ou *Responsabilidade Única* - Envolva os componentes Angular em uma *Immediately Invoked Function Expression (IIFE - Expressão de função imediatamente invocada)*. - **Por que?** Uma IIFE remove as variáveis do escopo global. Isso ajuda a prevenir declarações de variáveis e funções de viverem por mais tempo que o esperado no escopo global, que também auxilia evitar colisões de variáveis. + **Por quê?** Uma IIFE remove as variáveis do escopo global. Isso ajuda a prevenir declarações de variáveis e funções de viverem por mais tempo que o esperado no escopo global, que também auxilia evitar colisões de variáveis. - **Por que?** Quando seu código é minificado e empacotado dentro de um único arquivo para *deployment* no servidor de produção, você pode ter conflitos de variáveis e muitas variáveis globais. Uma IIFE o protege em todos estes aspectos provendo escopo de variável para cada arquivo. + **Por quê?** Quando seu código é minificado e empacotado dentro de um único arquivo para *deployment* no servidor de produção, você pode ter conflitos de variáveis e muitas variáveis globais. Uma IIFE o protege em todos estes aspectos provendo escopo de variável para cada arquivo. ```javascript /* evite */ @@ -183,7 +183,7 @@ ou *Evitando Colisão de Nomes* - Use uma única convenção de nomes com separadores para sub-módulos. - **Por que?** Nomes únicos ajudam a evitar colisão de nomes no módulo. Separadores ajudam a definir a hierarquia de módulos e submódulos. Por exemplo, `app` pode ser seu módulo raiz, enquanto `app.dashboard` e `app.users` podem ser módulos que são usados como dependências de `app`. + **Por quê?** Nomes únicos ajudam a evitar colisão de nomes no módulo. Separadores ajudam a definir a hierarquia de módulos e submódulos. Por exemplo, `app` pode ser seu módulo raiz, enquanto `app.dashboard` e `app.users` podem ser módulos que são usados como dependências de `app`. ### Definições (*aka Setters*) @@ -191,7 +191,7 @@ ou *Evitando Colisão de Nomes* - Declare os módulos sem uma variável usando a sintaxe *setter*. - **Por que?** Com 1 componente por arquivo, raramente será necessário criar uma variável para o módulo. + **Por quê?** Com 1 componente por arquivo, raramente será necessário criar uma variável para o módulo. ```javascript /* evite */ @@ -220,7 +220,7 @@ ou *Evitando Colisão de Nomes* - Ao usar um módulo, evite usar uma variável. Em vez disso, use encadeamento com a sintaxe *getter*. - **Por que?** Isso produz um código mais legível e evita colisão de variáveis ou vazamentos. + **Por quê?** Isso produz um código mais legível e evita colisão de variáveis ou vazamentos. ```javascript /* evite */ @@ -244,7 +244,7 @@ ou *Definindo* vs *Obtendo* - Apenas *set* (configure) uma vez e *get* (receba) em todas as outras instâncias. - **Por que?** Um módulo deve ser criado somente uma vez, então recupere-o deste ponto em diante. + **Por quê?** Um módulo deve ser criado somente uma vez, então recupere-o deste ponto em diante. - Use `angular.module('app', []);` para definir (*set*) um módulo. - Use `angular.module('app');` para pegar (*get*) este módulo. @@ -254,7 +254,7 @@ ou *Funções Nomeadas vs Funções Anônimas* - Use funções nomeadas ao invés de passar uma função anônima como um callback. - **Por que?** Isso produz um código mais legível, é muito fácil de *debugar*, e reduz a quantidade de callbacks aninhados no código. + **Por quê?** Isso produz um código mais legível, é muito fácil de *debugar*, e reduz a quantidade de callbacks aninhados no código. ```javascript /* evite */ @@ -293,11 +293,11 @@ ou *Controladores* - Utilize a sintaxe [`controllerAs`](http://www.johnpapa.net/do-you-like-your-angular-controllers-with-or-without-sugar/) ao invés da sintaxe `clássica controller com $scope`. - **Por que?** Controllers são construídos, "iniciados", e fornecem um nova instância única, e a sintaxe `controllerAs` é mais próxima de um construtor JavaScript do que a `sintaxe clássica do $scope`. + **Por quê?** Controllers são construídos, "iniciados", e fornecem um nova instância única, e a sintaxe `controllerAs` é mais próxima de um construtor JavaScript do que a `sintaxe clássica do $scope`. - **Por que?** Isso promove o uso do binding de um objeto "pontuado", ou seja, com propriedades na View (ex. `customer.name` ao invés de `name`), que é mais contextual, legível, e evita qualquer problema com referências que podem ocorrer sem a "pontuação" + **Por quê?** Isso promove o uso do binding de um objeto "pontuado", ou seja, com propriedades na View (ex. `customer.name` ao invés de `name`), que é mais contextual, legível, e evita qualquer problema com referências que podem ocorrer sem a "pontuação" - **Por que?** Ajuda a evitar o uso de chamadas ao `$parent` nas Views com controllers aninhados. + **Por quê?** Ajuda a evitar o uso de chamadas ao `$parent` nas Views com controllers aninhados. ```html @@ -319,9 +319,9 @@ ou *Controladores* - A sintaxe `controllerAs` usa o `this` dentro dos controllers que fica ligado ao `$scope`. - **Por que?** O `controllerAs` é uma forma mais simples de lidar com o `$scope`. Você ainda poderá fazer o bind para a View e ainda poderá acessar os métodos do `$scope`. + **Por quê?** O `controllerAs` é uma forma mais simples de lidar com o `$scope`. Você ainda poderá fazer o bind para a View e ainda poderá acessar os métodos do `$scope`. - **Por que?** Ajuda a evitar a tentação de usar os métodos do `$scope` dentro de um controller quando seria melhor evitá-los ou movê-los para um factory. Considere utilizar o `$scope` em um factory, ou em um controller apenas quando necessário. Por exemplo, quando publicar e subscrever eventos usando [`$emit`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$emit), [`$broadcast`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$broadcast), ou [`$on`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$on) considere mover estes casos para um factory e invocá-los a partir do controller. + **Por quê?** Ajuda a evitar a tentação de usar os métodos do `$scope` dentro de um controller quando seria melhor evitá-los ou movê-los para um factory. Considere utilizar o `$scope` em um factory, ou em um controller apenas quando necessário. Por exemplo, quando publicar e subscrever eventos usando [`$emit`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$emit), [`$broadcast`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$broadcast), ou [`$on`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$on) considere mover estes casos para um factory e invocá-los a partir do controller. ```javascript /* evite */ @@ -343,7 +343,7 @@ ou *Controladores* - Utilize uma variável de captura para o `this` quando usar a sintaxe `controllerAs`. Escolha um nome de variável consistente como `vm`, que representa o ViewModel. - **Por que?** A palavra-chave `this` é contextual e quando usada em uma função dentro de um controller pode mudar seu contexto. Capturando o contexto do `this` evita a ocorrência deste problema. + **Por quê?** A palavra-chave `this` é contextual e quando usada em uma função dentro de um controller pode mudar seu contexto. Capturando o contexto do `this` evita a ocorrência deste problema. ```javascript /* evite */ @@ -382,9 +382,9 @@ ou *Controladores* - Coloque os objetos que precisam de bind no início do controller, em ordem alfabética, e não espalhados através do código do controller. - **Por que?** Colocar os objetos que precisam de bind no início torna mais fácil de ler e te ajuda a instantaneamente identificar quais objetos do controller podem ser utilizados na View. + **Por quê?** Colocar os objetos que precisam de bind no início torna mais fácil de ler e te ajuda a instantaneamente identificar quais objetos do controller podem ser utilizados na View. - **Por que?** Setar funções anônimas pode ser fácil, mas quando essas funções possuem mais de 1 linha do código elas podem dificultar a legibilidade. Definir as funções abaixo dos objetos que necessitam de bind (as funções serão elevadas pelo JavaScript Hoisting) move os detalhes de implementação para o final do controller, mantém os objetos que necessitam de bind no topo, e deixa o código mais fácil de se ler. + **Por quê?** Setar funções anônimas pode ser fácil, mas quando essas funções possuem mais de 1 linha do código elas podem dificultar a legibilidade. Definir as funções abaixo dos objetos que necessitam de bind (as funções serão elevadas pelo JavaScript Hoisting) move os detalhes de implementação para o final do controller, mantém os objetos que necessitam de bind no topo, e deixa o código mais fácil de se ler. ```javascript /* evite */ @@ -471,15 +471,15 @@ ou *Controladores* - Utilize declarações de funções para esconder detalhes de implementação. Mantenha seus objetos que necessitam de bind no topo. Quando você precisar fazer o bind de uma função no controller, aponte ela para a declaração de função que aparece no final do arquivo. Ela está ligada diretamente aos objetos que precisam de bind no início do arquivo. Para mais detalhes veja [este post](http://www.johnpapa.net/angular-function-declarations-function-expressions-and-readable-code). - **Por que?** Colocar os objetos que precisam de bind no início torna mais fácil de ler e te ajuda a instantaneamente identificar quais objetos do controller podem ser utilizados na View. (Mesmo do item anterior.) + **Por quê?** Colocar os objetos que precisam de bind no início torna mais fácil de ler e te ajuda a instantaneamente identificar quais objetos do controller podem ser utilizados na View. (Mesmo do item anterior.) - **Por que?** Colocar os detalhes de implementação de uma função no final do arquivo coloca a complexidade fora do foco, logo, você pode focar nas coisas importantes no topo. + **Por quê?** Colocar os detalhes de implementação de uma função no final do arquivo coloca a complexidade fora do foco, logo, você pode focar nas coisas importantes no topo. - **Por que?** Declarações de funções são içadas, logo, não existe problema de se utilizar uma função antes dela ser definida (como haveria com expressões de função). + **Por quê?** Declarações de funções são içadas, logo, não existe problema de se utilizar uma função antes dela ser definida (como haveria com expressões de função). - **Por que?** Você nunca precisará se preocupar com declarações de funções quebrarem seu código por colocar `var a` antes de `var b` por que `a` depende de `b`. + **Por quê?** Você nunca precisará se preocupar com declarações de funções quebrarem seu código por colocar `var a` antes de `var b` por que `a` depende de `b`. - **Por que?** A ordenação é crítica em expressões de função. + **Por quê?** A ordenação é crítica em expressões de função. ```javascript /** @@ -545,11 +545,11 @@ ou *Controladores* - Remova a lógica do controller delegando ela a services e factories. - **Por que?** A lógica pode ser reutilizada em múltiplos controllers quando colocada em um service e exposta através de uma função. + **Por quê?** A lógica pode ser reutilizada em múltiplos controllers quando colocada em um service e exposta através de uma função. - **Por que?** A lógica em um serviço pode ser mais facilmente isolada em um teste unitário, enquanto a lógica feita no controlador pode ser facilmente [mockada](http://www.thoughtworks.com/pt/insights/blog/mockists-are-dead-long-live-classicists). + **Por quê?** A lógica em um serviço pode ser mais facilmente isolada em um teste unitário, enquanto a lógica feita no controlador pode ser facilmente [mockada](http://www.thoughtworks.com/pt/insights/blog/mockists-are-dead-long-live-classicists). - **Por que?** Remove as dependências e esconde os detalhes de implementação do controlador. + **Por quê?** Remove as dependências e esconde os detalhes de implementação do controlador. ```javascript /* evite */ @@ -585,7 +585,7 @@ ou *Controladores* - Defina um controller para a view e tente não reutilizar o controller para outras views. Ao invés disso, coloque as lógicas reaproveitáveis em factories e mantenha o controller simples e focado em sua view. - **Por que?** Reutilizar controllers em várias views é arriscado e um boa cobertura de testes end to end (e2e) é obrigatório para se garantir estabilidade em grandes aplicações. + **Por quê?** Reutilizar controllers em várias views é arriscado e um boa cobertura de testes end to end (e2e) é obrigatório para se garantir estabilidade em grandes aplicações. ### Assigning Controllers @@ -593,7 +593,7 @@ ou *Controladores* Nota: Se uma View é carregada de outra forma que não seja através de uma rota, então utilize a sintaxe `ng-controller="Avengers as vm"`. - **Por que?** Parear os controllers nas rotas permite diferentes rotas invocarem diferentes pares de controllers e views. Quando um controller é utilizado na view usando a sintaxe [`ng-controller`](https://docs.angularjs.org/api/ng/directive/ngController), esta view sempre será associada ao mesmo controller. + **Por quê?** Parear os controllers nas rotas permite diferentes rotas invocarem diferentes pares de controllers e views. Quando um controller é utilizado na view usando a sintaxe [`ng-controller`](https://docs.angularjs.org/api/ng/directive/ngController), esta view sempre será associada ao mesmo controller. ```javascript /* evite - quando utilizar com uma rota e emparelhamento dinâmico é desejado */ @@ -701,11 +701,11 @@ ou *Membros acessíveis no topo* - Exponha os membros que podem ser invocados no serviço (a interface) no topo, utilizando uma técnica derivada do [Revealing Module Pattern](http://addyosmani.com/resources/essentialjsdesignpatterns/book/#revealingmodulepatternjavascript). - **Por que?** Colocando no topo os membros que podem ser invocados da factory, a leitura torna-se mais fácil e ajuda a identificar imediatamente quais membros da factory podem ser invocados e testados através de teste unitário (e/ou mock). + **Por quê?** Colocando no topo os membros que podem ser invocados da factory, a leitura torna-se mais fácil e ajuda a identificar imediatamente quais membros da factory podem ser invocados e testados através de teste unitário (e/ou mock). - **Por que?** É especialmente útil quando o arquivo torna-se muito longo e ajuda a evitar a necessidade de rolagem para ver o que é exposto. + **Por quê?** É especialmente útil quando o arquivo torna-se muito longo e ajuda a evitar a necessidade de rolagem para ver o que é exposto. - **Por que?** Definir as funções conforme você escreve o código pode ser fácil, mas quando essas funções tem mais que 1 linha de código, elas podem reduzir a leitura e causar rolagem. Definir a interface no topo do que pode ser invocado da factory, torna a leitura mais fácil e mantém os detalhes de implementação mais abaixo. + **Por quê?** Definir as funções conforme você escreve o código pode ser fácil, mas quando essas funções tem mais que 1 linha de código, elas podem reduzir a leitura e causar rolagem. Definir a interface no topo do que pode ser invocado da factory, torna a leitura mais fácil e mantém os detalhes de implementação mais abaixo. ```javascript /* evite */ @@ -758,15 +758,15 @@ ou *Declarações de função para esconder detalhes de implementação* - Use function declarations (declarações de função) para esconder detalhes de implementação. Mantenha os membros acessíveis da factory no topo. Aponte as function declarations que aparecem posteriormente no arquivo. Para mais detalhes leia [esse post](http://www.johnpapa.net/angular-function-declarations-function-expressions-and-readable-code). - **Por que?** Colocando os membros acessíveis no topo, a leitura torna-se mais fácil e ajuda a identificar imediatamente quais membros da factory podem ser acessados externamente. + **Por quê?** Colocando os membros acessíveis no topo, a leitura torna-se mais fácil e ajuda a identificar imediatamente quais membros da factory podem ser acessados externamente. - **Por que?** Colocando os detalhes de implementação da função posteriormente no arquivo move a complexidade para fora da visão, permitindo que você veja as coisas mais importantes no topo. + **Por quê?** Colocando os detalhes de implementação da função posteriormente no arquivo move a complexidade para fora da visão, permitindo que você veja as coisas mais importantes no topo. - **Por que?** Function declarations (declarações de função) são içadas (hoisted) para que não hajam preocupações em utilizar uma função antes que ela seja definida (como haveria com function expressions (expressões de função)). + **Por quê?** Function declarations (declarações de função) são içadas (hoisted) para que não hajam preocupações em utilizar uma função antes que ela seja definida (como haveria com function expressions (expressões de função)). - **Por que?** Você nunca deve se preocupar com function declaration (declarações de função) onde `var a` está antes de `var b` vai ou não quebrar o seu código porque `a` depende de `b`. + **Por quê?** Você nunca deve se preocupar com function declaration (declarações de função) onde `var a` está antes de `var b` vai ou não quebrar o seu código porque `a` depende de `b`. - **Por que?** A ordem é crítica com function expressions (expressões de função) + **Por quê?** A ordem é crítica com function expressions (expressões de função) ```javascript /** @@ -861,11 +861,11 @@ ou *Chamadas de dados separadas* - A lógica de refatoração (refactor) para operações com dados e interação com dados na factory. Faça serviços de dados responsáveis por chamadas XHR, armazenamento local (local storage), armazenamento em memória (stashing) ou outras operações com dados. - **Por que?** A responsabilidade dos controladores (controllers) é para a apresentação e coleta de informações da view. Eles não devem se importar como os dados são adquiridos, somente como "perguntar" por eles. Separar os serviços de dados (data services), move a lógica de como adquiri-los para o serviço e deixa o controlador (controller) mais simples e focado na view. + **Por quê?** A responsabilidade dos controladores (controllers) é para a apresentação e coleta de informações da view. Eles não devem se importar como os dados são adquiridos, somente como "perguntar" por eles. Separar os serviços de dados (data services), move a lógica de como adquiri-los para o serviço e deixa o controlador (controller) mais simples e focado na view. - **Por que?** Isso torna mais fácil testar (mock ou real) as chamadas de dados quando estiver testando um controlador (controller) que utiliza um serviço de dados (data service). + **Por quê?** Isso torna mais fácil testar (mock ou real) as chamadas de dados quando estiver testando um controlador (controller) que utiliza um serviço de dados (data service). - **Por que?** A implementação de um serviço de dados (data service) pode ter um código bem específico para lidar com o repositório de dados. Isso pode incluir cabeçalhos (headers), como comunicar com os dados ou outros serviços, como $http. Separando a lógica de dados em um serviço, coloca toda a lógica somente em um local e esconde a implementação de consumidores de fora (talvez um controlador (controller)), tornado mais fácil mudar a implementação. + **Por quê?** A implementação de um serviço de dados (data service) pode ter um código bem específico para lidar com o repositório de dados. Isso pode incluir cabeçalhos (headers), como comunicar com os dados ou outros serviços, como $http. Separando a lógica de dados em um serviço, coloca toda a lógica somente em um local e esconde a implementação de consumidores de fora (talvez um controlador (controller)), tornado mais fácil mudar a implementação. ```javascript /* recomendado */ @@ -937,7 +937,7 @@ ou *Retorne uma promessa de chamadas de dados* - Quando chamar um serviço de dados (data service) que retorna uma promessa (promise), como o $http, retorne uma promessa (promise) na função que está chamando também. - **Por que?** Você pode encandear as promessas (promises) juntas e definir ações após a promessa (promise) da chamada do dado ser completada, resolvendo ou rejeitando a promessa (promise). + **Por quê?** Você pode encandear as promessas (promises) juntas e definir ações após a promessa (promise) da chamada do dado ser completada, resolvendo ou rejeitando a promessa (promise). ```javascript /* recomendado */ @@ -987,9 +987,9 @@ ou *Limite 1 por arquivo* - Crie uma diretiva (directive) por arquivo. Nomeie o arquivo pela diretiva. - **Por que?** É fácil misturar todas as diretivas em um arquivo, mas é difícil depois separá-las, já que algumas são compartilhadas entre aplicativos, outras pelos módulos (modules) e algumas somente para um módulo. + **Por quê?** É fácil misturar todas as diretivas em um arquivo, mas é difícil depois separá-las, já que algumas são compartilhadas entre aplicativos, outras pelos módulos (modules) e algumas somente para um módulo. - **Por que?** Uma diretiva (directive) por arquivo é mais fácil de dar manutenção. + **Por quê?** Uma diretiva (directive) por arquivo é mais fácil de dar manutenção. ```javascript /* evite */ @@ -1079,14 +1079,14 @@ ou *Limite a manipulação do DOM* - Quando estiver manipulando o DOM diretamente, utilize uma diretiva (directive). Se formas alternativas podem ser utilizadas, como: utilizar CSS para setar estilos ou [serviços de animação (animation services)](https://docs.angularjs.org/api/ngAnimate), Angular templating, [`ngShow`](https://docs.angularjs.org/api/ng/directive/ngShow) ou [`ngHide`](https://docs.angularjs.org/api/ng/directive/ngHide), então prefira utilizá-los. Por exemplo, se uma diretiva simplesmente esconde ou mostra um elemento, use ngHide/ngShow. - **Por que?** A manipulação do DOM pode ser difícil de testar, debugar, e há melhores maneiras (ex: CSS, animações (animations), templates). + **Por quê?** A manipulação do DOM pode ser difícil de testar, debugar, e há melhores maneiras (ex: CSS, animações (animations), templates). ### Provide a Unique Directive Prefix ou *Forneça um prefixo único para as diretivas* - Forneça um curto, único e descritivo prefixo para a diretiva, como `acmeSalesCustomerInfo`, que é declarado no HTML como `acme-sales-customer-info`. - **Por que?** Um prefixo curto e único identifica o contexto e a origem da diretiva. Por exemplo, o prefixo `cc-` pode indicar que a diretiva é parte de um aplicativo da CodeCamper, enquanto a diretiva `acme-` pode indicar uma diretiva para a companhia Acme. + **Por quê?** Um prefixo curto e único identifica o contexto e a origem da diretiva. Por exemplo, o prefixo `cc-` pode indicar que a diretiva é parte de um aplicativo da CodeCamper, enquanto a diretiva `acme-` pode indicar uma diretiva para a companhia Acme. Nota: Evite `ng-`, pois são reservadas para as diretivas do AngularJS. Pesquise largamente as diretivas utilizadas para evitar conflitos de nomes, como `ion-` que são utilizadas para o [Ionic Framework](http://ionicframework.com/). @@ -1095,9 +1095,9 @@ ou *Restringir para elementos e atributos* - Quando criar uma diretiva que faça sentido por si só como um elemento, utilize restrição `E` (elemento personalizado) e opcionalmente `A` (atributo personalizado). Geralmente, se ela pode ter o seu próprio controlador (controller), `E` é o apropriado. Em linhas gerais, `EA` é permitido, mas atente para a implementação como elemento quando faz sentido por si só e como atributo quando estende algo existente no DOM. - **Por que?** Faz sentido. + **Por quê?** Faz sentido. - **Por que?** Nós podemos utilizar uma diretiva como uma classe (class), mas se a diretiva está realmente agindo como um elemento, faz mais sentido utilizar como um elemento, ou pelo menos como um atributo. + **Por quê?** Nós podemos utilizar uma diretiva como uma classe (class), mas se a diretiva está realmente agindo como um elemento, faz mais sentido utilizar como um elemento, ou pelo menos como um atributo. Nota: EA é o padrão para o Angular 1.3 + @@ -1157,7 +1157,7 @@ ou *Diretivas e "ControladorComo"* - Utilize a sintaxe `controller as` com uma diretiva para consistência com o uso de `controller as` com os pares view e controlador (controller). - **Por que?** Faz sentido e não é difícil. + **Por quê?** Faz sentido e não é difícil. Nota: A diretiva (directive) abaixo demonstra algumas maneiras que você pode utilizar escopos (scopes) dentro de link e controller de uma diretiva, utilizando controllerAs. Eu coloquei o template somente para manter tudo em um mesmo local. @@ -1221,7 +1221,7 @@ ou *Ativação de promessas no controlador* - Resolva a lógica de inicialização no controlador (controller) em uma função `iniciar`. - **Por que?** Colocando a lógica de inicialização em um lugar consistente no controlador (controller), torna mais fácil de localizar, mais consistente para testar e ajuda a evitar o espalhamento da lógica de inicialização pelo controlador (controller). + **Por quê?** Colocando a lógica de inicialização em um lugar consistente no controlador (controller), torna mais fácil de localizar, mais consistente para testar e ajuda a evitar o espalhamento da lógica de inicialização pelo controlador (controller). Nota: Se você precisa cancelar a rota condicionalmente antes de utilizar o controlador (controller), utilize uma resolução de rota (route resolve). @@ -1264,7 +1264,7 @@ ou *Resolução de promessas na rota* - Quando o controlador (controller) depende de uma promessa ser resolvida, resolva as dependências no `$routeProvider` antes da lógica do controlador (controller) ser executada. Se você precisa cancelar a rota condicionalmente antes do controlador (controller) ser ativado, utilize uma resolução de rota (route resolve). - **Por que?** Um controlador (controller) pode precisar de dados antes de ser carregado. Esses dados podem vir de uma promessa (promise) através de uma factory personalizada ou [$http](https://docs.angularjs.org/api/ng/service/$http). Utilizar [resolução de rota (route resolve)](https://docs.angularjs.org/api/ngRoute/provider/$routeProvider) permite as promessas (promises) serem resolvidas antes da lógica do controlador (controller) ser executada, então ele pode executar ações através dos dados dessa promessa (promise). + **Por quê?** Um controlador (controller) pode precisar de dados antes de ser carregado. Esses dados podem vir de uma promessa (promise) através de uma factory personalizada ou [$http](https://docs.angularjs.org/api/ng/service/$http). Utilizar [resolução de rota (route resolve)](https://docs.angularjs.org/api/ngRoute/provider/$routeProvider) permite as promessas (promises) serem resolvidas antes da lógica do controlador (controller) ser executada, então ele pode executar ações através dos dados dessa promessa (promise). ```javascript /* evite */ @@ -1330,7 +1330,7 @@ ou *Não seguro para Minificação* - Evite usar o atalho de sintaxe de declarar dependências sem usar uma abordagem segura para minificação. - **Por que?** Os parâmetros do componente (por ex. controller, factory, etc) serão convertidos em variáveis encurtadas. Por exemplo, `common` e `dataservice` podem virar `a` ou `b` e não serem encontrados pelo AngularJS. + **Por quê?** Os parâmetros do componente (por ex. controller, factory, etc) serão convertidos em variáveis encurtadas. Por exemplo, `common` e `dataservice` podem virar `a` ou `b` e não serem encontrados pelo AngularJS. ```javascript /* evite - não seguro para minificação*/ @@ -1354,11 +1354,11 @@ ou *Identifique Dependências Manualmente* - Use `$inject` para identificar manualmente suas dependências de componentes do AngularJS. - **Por que?** Esta técnica espelha a técnica usada por [`ng-annotate`](https://github.com/olov/ng-annotate), a qual eu recomendo para automatizar a criação de dependências seguras para minificação. Se `ng-annotate` detectar que a injeção já foi feita, ela não será duplicada. + **Por quê?** Esta técnica espelha a técnica usada por [`ng-annotate`](https://github.com/olov/ng-annotate), a qual eu recomendo para automatizar a criação de dependências seguras para minificação. Se `ng-annotate` detectar que a injeção já foi feita, ela não será duplicada. - **Por que?** Isto salvaguarda suas dependências de serem vulneráveis a problemas de minificação quando parâmetros podem ser encurtados. Por exemplo, `common` e `dataservice` podem se tornar `a` ou `b` e não serem encontrados pelo AngularJS. + **Por quê?** Isto salvaguarda suas dependências de serem vulneráveis a problemas de minificação quando parâmetros podem ser encurtados. Por exemplo, `common` e `dataservice` podem se tornar `a` ou `b` e não serem encontrados pelo AngularJS. - **Por que?** Evite criar dependências in-line pois listas longas podem ser difíceis de ler no array. Além disso, pode ser confuso o array ser uma série de strings enquanto o último item é a função do componente. + **Por quê?** Evite criar dependências in-line pois listas longas podem ser difíceis de ler no array. Além disso, pode ser confuso o array ser uma série de strings enquanto o último item é a função do componente. ```javascript /* evite */ @@ -1428,9 +1428,9 @@ ou *Identifique Dependências do Resolvedor de Rotas Manualmente* - Use $inject para identificar manualmente as dependências do seu resolvedor de rotas para componentes do AngularJS. - **Por que?** Esta técnica separa a função anônima do resolvedor de rota, tornando-a mais fácil de ler. + **Por quê?** Esta técnica separa a função anônima do resolvedor de rota, tornando-a mais fácil de ler. - **Por que?** Uma chamada a `$inject` pode facilmente preceder o resolvedor para fazer qualquer dependência segura para minificação. + **Por quê?** Uma chamada a `$inject` pode facilmente preceder o resolvedor para fazer qualquer dependência segura para minificação. ```javascript /* recomendado */ @@ -1461,9 +1461,9 @@ ou *Minificação e Anotação* - Use [ng-annotate](//github.com/olov/ng-annotate) para [Gulp](http://gulpjs.com) ou [Grunt](http://gruntjs.com) e comente as funções que precisam de injeção de dependência automatizada usando `/** @ngInject */` - **Por que?** Isso protege seu código de qualquer dependência que pode não estar usando práticas seguras para minificação. + **Por quê?** Isso protege seu código de qualquer dependência que pode não estar usando práticas seguras para minificação. - **Por que?** [`ng-min`](https://github.com/btford/ngmin) está deprecated. + **Por quê?** [`ng-min`](https://github.com/btford/ngmin) está deprecated. > Eu prefiro Gulp pois sinto que é mais fácil de escrever, de ler, e de debugar. @@ -1537,7 +1537,7 @@ ou *Minificação e Anotação* - Utilize [gulp-ng-annotate](https://www.npmjs.org/package/gulp-ng-annotate) ou [grunt-ng-annotate](https://www.npmjs.org/package/grunt-ng-annotate) para tarefas de build automatizadas. Injete `/* @ngInject */` antes de qualquer função que tenha dependências. - **Por que?** ng-annotate vai capturar todas as dependências, mas as vezes requer dicas utilizando a sintaxe `/* @ngInject */` . + **Por quê?** ng-annotate vai capturar todas as dependências, mas as vezes requer dicas utilizando a sintaxe `/* @ngInject */` . O código abaixo é um exemplo de uma task Gulp utilizando ngAnnotate @@ -1572,7 +1572,7 @@ ou *decoradores* - Utilize um [decorator](https://docs.angularjs.org/api/auto/service/$provide#decorator), no seu config utilizando o serviço [`$provide`](https://docs.angularjs.org/api/auto/service/$provide), no serviço [`$exceptionHandler`](https://docs.angularjs.org/api/ng/service/$exceptionHandler) para realizar ações customizadas quando um erro ocorrer. - **Por que?** Fornece um caminho consistente para manipular erros não tratados pelo Angular em tempo de desenvolvimento ou execução (run-time). + **Por quê?** Fornece um caminho consistente para manipular erros não tratados pelo Angular em tempo de desenvolvimento ou execução (run-time). Nota: Outra opção é sobrescrever o serviço ao invés de utilizar um decorator. Esta é uma boa opção, mas se você quer manter o comportamento padrão e estender, o decorator é recomendado. @@ -1613,7 +1613,7 @@ ou *Coletores de exceção* - Criar um factory que expõe uma interface para capturar e tratar adequadamente as exceções. - **Por que?** Fornece uma forma consistente de coletar exceções que podem ser lançadas no seu código (ex. durante uma chamada XHR ou uma promessa (promise) que falhou). + **Por quê?** Fornece uma forma consistente de coletar exceções que podem ser lançadas no seu código (ex. durante uma chamada XHR ou uma promessa (promise) que falhou). Nota: O coletor de exceção é bom para coletar e reagir às exceções específicas das chamadas que você sabe que podem ser lançadas. Por exemplo, quando realizar uma chamada XHR que retorna dados de um serviço remoto e você quer coletar qualquer exceção desse serviço, reagindo de uma maneira única. @@ -1643,9 +1643,9 @@ ou *Coletores de exceção* - Gerencie e log todos os erros de routing utilizando o [`$routeChangeError`](https://docs.angularjs.org/api/ngRoute/service/$route#$routeChangeError). - **Por que?** Fornece uma maneira consistente de gerenciar erros relacionados a routing. + **Por quê?** Fornece uma maneira consistente de gerenciar erros relacionados a routing. - **Por que?** Potencialmente fornece uma melhor experiência de usuário se um erro de routing ocorrer e você redirecionar o usuário para uma tela amigável com mais detalhes ou opções de recuperação. + **Por quê?** Potencialmente fornece uma melhor experiência de usuário se um erro de routing ocorrer e você redirecionar o usuário para uma tela amigável com mais detalhes ou opções de recuperação. ```javascript /* recomendado */ @@ -1681,18 +1681,18 @@ ou *Nomenclatura* * o nome do arquivo (`avengers.controllers.js`) * o nome de componente registrado pelo Angular (`AvengersController`) - **Por que?** As convenções de nomenclatura ajudam a fornecer uma maneira consistente de encontrar algo à primeira vista. Consistência dentro do projeto é vital. Consistência dentro de um time é importante. Consistência em toda a empresa proporciona uma enorme eficiência. + **Por quê?** As convenções de nomenclatura ajudam a fornecer uma maneira consistente de encontrar algo à primeira vista. Consistência dentro do projeto é vital. Consistência dentro de um time é importante. Consistência em toda a empresa proporciona uma enorme eficiência. - **Por que?** As convenções de nomenclatura deveriam simplesmente te ajudar a encontrar trechos do seu código mais rápido e torná-lo mais fácil de se entender. + **Por quê?** As convenções de nomenclatura deveriam simplesmente te ajudar a encontrar trechos do seu código mais rápido e torná-lo mais fácil de se entender. ### Feature File Names ou *Nome para funcionalidades* - Use nomes consistentes para todos os componentes seguindo um padrão que descreve a funcionalidade do componente e, em seguida, (opcionalmente) o seu tipo. Meu padrão recomendado é `feature.type.js`. - **Por que?** Fornece uma maneira consistente para identificar componentes mais rapidamente. + **Por quê?** Fornece uma maneira consistente para identificar componentes mais rapidamente. - **Por que?** Fornece um padrão apropriado pra qualquer tarefa automatizada. + **Por quê?** Fornece um padrão apropriado pra qualquer tarefa automatizada. ```javascript /** @@ -1757,9 +1757,9 @@ ou *Nome para aquivos de testes* - Nomeie as especificações de testes de forma similar aos componentes que elas testam, com o sufixo `spec`. - **Por que?** Fornece um modo consistente para identificar rapidamente os componentes. + **Por quê?** Fornece um modo consistente para identificar rapidamente os componentes. - **Por que?** Fornece padrões de correspondência para o [karma](http://karma-runner.github.io/) ou outros test runners. + **Por quê?** Fornece padrões de correspondência para o [karma](http://karma-runner.github.io/) ou outros test runners. ```javascript /** @@ -1776,9 +1776,9 @@ ou *Nomes para controller* - Use nomes consistentes para todos os controllers nomeados após as sua funcionalidade. Use UpperCamelCase para os controllers, assim como para seus construtores. - **Por que?** Fornece um modo consistente para identificar e referenciar os controllers. + **Por quê?** Fornece um modo consistente para identificar e referenciar os controllers. - **Por que?** O UpperCamelCase é o modo mais comum para identificar objetos que serão instanciados através de construtores. + **Por quê?** O UpperCamelCase é o modo mais comum para identificar objetos que serão instanciados através de construtores. ```javascript /** @@ -1798,7 +1798,7 @@ ou *sufixo "Controllers"* - Complemente o nome do controller com ou sem o sufixo `Controller`. Escolha uma opção, não ambas. - **Por que?** O sufixo `Controller` é mais usado e mais descritivo. + **Por quê?** O sufixo `Controller` é mais usado e mais descritivo. ```javascript /** @@ -1831,9 +1831,9 @@ ou *Nomes para factory* - Use nomes consistentes para todas as factories nomeadas após sua funcionalidade. Use a conveção camelCase para services e factories. Evite prefixos com `$`. - **Por que?** Fornece um modo consistente de identificar e referenciar rapidamente as factories. + **Por quê?** Fornece um modo consistente de identificar e referenciar rapidamente as factories. - **Por que?** Evite colisão de nomes com factories e services pré-programados que usam o prefixo `$`. + **Por quê?** Evite colisão de nomes com factories e services pré-programados que usam o prefixo `$`. ```javascript /** @@ -1853,7 +1853,7 @@ ou *Nomes para directive* - Use nomes consistentes para todas as directives usando a convenção camelCase. Use um prefixo curto para descrever a área a qual a directive pertence (como prefixo da compania ou do projeto). - **Por que?** Fornece um modo consistente de identificar e referenciar rapidamente os componentes. + **Por quê?** Fornece um modo consistente de identificar e referenciar rapidamente os componentes. ```javascript /** @@ -1875,18 +1875,18 @@ ou *Módulos* - Quando há vários módulos, o arquivo principal deste módulo é nomeado `app.module.js`, enquanto os módulos dependentes são nomeados de acordo com o que eles representam. Por exemplo, um módulo admin é nomeado `admin.module.js`. Os nomes dos respectivos módulos registrados seriam `app` e `admin`. - **Por que?** Fornece consistência para múltiplos módulos, e para expansão para grandes aplicações. + **Por quê?** Fornece consistência para múltiplos módulos, e para expansão para grandes aplicações. - **Por que?** Fornece um modo fácil para automação de tarefas, a fim de carregar todos as definições dos módulos em primeiro lugar, então os demais arquivos (empacotamento). + **Por quê?** Fornece um modo fácil para automação de tarefas, a fim de carregar todos as definições dos módulos em primeiro lugar, então os demais arquivos (empacotamento). ### Configuration ou *Configuração* - Separe a configuração do módulo em seu próprio arquivo, nomeado após o módulo. Um arquivo de configuração para o módulo principal `app` é nomeado `app.config.js` (ou simplesmente `config.js`). Uma configuração para o módulo `admin.module.js` é nomeada `admin.config.js`. - **Por que?** Separa a configuração do módulo da definição, dos componentes e do código ativo. + **Por quê?** Separa a configuração do módulo da definição, dos componentes e do código ativo. - **Por que?** Fornece um local identificável para definir as configurações de um módulo. + **Por quê?** Fornece um local identificável para definir as configurações de um módulo. ### Routes ou *Rotas* @@ -1916,7 +1916,7 @@ ou *Localizar* - Torne a localização do seu código: intuitiva, simples e rápida. - **Por que?** Acho que isso é super importante para um projeto. Se a equipe não pode encontrar rapidamente os arquivos que precisam para trabalhar, eles não serão capazes de trabalhar da forma mais eficiente possível, e a estrutura precisa mudar. Você pode não saber o nome do arquivo ou onde os arquivos relacionados estão, por isso, colocando-os nos locais mais intuitivos e próximos uns dos outros, economiza uma boa parcela de tempo. Uma pasta descrevendo a estrutura pode ajudá-lo. + **Por quê?** Acho que isso é super importante para um projeto. Se a equipe não pode encontrar rapidamente os arquivos que precisam para trabalhar, eles não serão capazes de trabalhar da forma mais eficiente possível, e a estrutura precisa mudar. Você pode não saber o nome do arquivo ou onde os arquivos relacionados estão, por isso, colocando-os nos locais mais intuitivos e próximos uns dos outros, economiza uma boa parcela de tempo. Uma pasta descrevendo a estrutura pode ajudá-lo. ``` /bower_components @@ -1941,21 +1941,21 @@ ou *Identificar* - Quando você olhar para um arquivo, prontamente você deve saber o que ele contém e o que representa. - **Por que?** Você gasta menos tempo caçando e procurando por código, e torna-se mais eficiente. Se isso significa nomes de arquivos mais longos, então que assim seja. Seja descritivo nos nomes de arquivos e mantenha o conteúdo do arquivo somente com 1 componente. Evite arquivos com vários controladores (controllers), múltiplos serviços (services), ou uma mistura. Existem exceções de 1 regra por arquivo quando eu tenho um conjunto de recursos muito pequenos que estão todos relacionados uns aos outros, eles ainda são facilmente identificáveis. + **Por quê?** Você gasta menos tempo caçando e procurando por código, e torna-se mais eficiente. Se isso significa nomes de arquivos mais longos, então que assim seja. Seja descritivo nos nomes de arquivos e mantenha o conteúdo do arquivo somente com 1 componente. Evite arquivos com vários controladores (controllers), múltiplos serviços (services), ou uma mistura. Existem exceções de 1 regra por arquivo quando eu tenho um conjunto de recursos muito pequenos que estão todos relacionados uns aos outros, eles ainda são facilmente identificáveis. ### Flat ou *Plano* - Mantenha uma estrutura plana de pastas o máximo que for possível. Quando você tiver 7 arquivos ou mais, comece a considerar separá-los. - **Por que?** Ninguém quer pesquisar 7 níveis de pastas para encontrar um arquivo. Pense sobre menus em web sites - nada mais profundo do que 2 níveis deve ser levado a sério. Em uma estrutura de pastas não há nenhum número mágico, mas quando uma pasta tem 7-10 arquivos, pode ser a hora de criar subpastas. Baseie-se no seu nível de conforto. Use uma estrutura mais plana até que haja um valor óbvio (para ajudar o resto do LIFT) na criação de uma nova pasta. + **Por quê?** Ninguém quer pesquisar 7 níveis de pastas para encontrar um arquivo. Pense sobre menus em web sites - nada mais profundo do que 2 níveis deve ser levado a sério. Em uma estrutura de pastas não há nenhum número mágico, mas quando uma pasta tem 7-10 arquivos, pode ser a hora de criar subpastas. Baseie-se no seu nível de conforto. Use uma estrutura mais plana até que haja um valor óbvio (para ajudar o resto do LIFT) na criação de uma nova pasta. ### T-DRY (Try to Stick to DRY) ou *Tente manter-se em DRY - Não repita a si mesmo* - Mantenha-se DRY, mas não fique louco e sacrifique a legibilidade. - **Por que?** Não ficar se repetindo é importante, mas não é crucial se acabar sacrificando os outros itens do LIFT, por isso eu chamo de T-DRY (Tente não ficar se repetindo). Eu não quero escrever session-view.html para uma view, porque obviamente é uma view. Se não é óbvio ou uma convenção, então eu renomeio. + **Por quê?** Não ficar se repetindo é importante, mas não é crucial se acabar sacrificando os outros itens do LIFT, por isso eu chamo de T-DRY (Tente não ficar se repetindo). Eu não quero escrever session-view.html para uma view, porque obviamente é uma view. Se não é óbvio ou uma convenção, então eu renomeio. **[De volta ao topo](#tabela-de-conte%C3%BAdo)** @@ -1973,20 +1973,20 @@ ou *Orientações gerais* - Coloque os componentes que definem o layout geral do aplicativo em uma pasta chamada `layout`. Eles podem incluir uma view e um controller que agem como recipiente para o app, navegação, menus, áreas de conteúdo, e outras regiões. - **Por que?** Organiza todos os layouts em um único lugar reutilizado em toda a aplicação. + **Por quê?** Organiza todos os layouts em um único lugar reutilizado em toda a aplicação. ### Folders-by-Feature Structure ou *Estrutura de Pastas-por-Recurso* - Crie pastas nomeadas para cada recurso que elas representam. Quando uma pasta cresce ao ponto de conter mais de 7 arquivos, comece considerar a criação de uma pasta para eles. O seu limite pode ser diferente, por isso, ajuste conforme necessário. - **Por que?** O desenvolvedor pode localizar o código, identificar o que cada arquivo representa em resumo, a estrutura é plana como deve ser, e não há nenhum nome repetido ou redundante. + **Por quê?** O desenvolvedor pode localizar o código, identificar o que cada arquivo representa em resumo, a estrutura é plana como deve ser, e não há nenhum nome repetido ou redundante. - **Por que?** As orientações LIFT estão todas sendo respeitadas. + **Por quê?** As orientações LIFT estão todas sendo respeitadas. - **Por que?** Através da organização do conteúdo, ajuda a reduzir o app de tornar-se desordenado e mantêm alinhado com as diretrizes LIFT. + **Por quê?** Através da organização do conteúdo, ajuda a reduzir o app de tornar-se desordenado e mantêm alinhado com as diretrizes LIFT. - **Por que?** Quando há um grande número de arquivos (10+) localizá-los é mais fácil com estruturas de pastas consistentes e mais difícil em estruturas planas. + **Por quê?** Quando há um grande número de arquivos (10+) localizá-los é mais fácil com estruturas de pastas consistentes e mais difícil em estruturas planas. ```javascript /** @@ -2079,32 +2079,32 @@ ou *Muitos módulos pequenos e independentes* - Crie pequenos módulos que encapsulem uma única responsabilidade. - **Por que?** Aplicações modulares tornam fácil o acoplamento, pois permitem que as equipes de desenvolvimento construam fatias verticais das aplicações e juntem tudo de forma incremental. Isto significa que podemos acoplar novos recursos enquanto os desenvolvemos. + **Por quê?** Aplicações modulares tornam fácil o acoplamento, pois permitem que as equipes de desenvolvimento construam fatias verticais das aplicações e juntem tudo de forma incremental. Isto significa que podemos acoplar novos recursos enquanto os desenvolvemos. ### Create an App Module ou *Crie um módulo da aplicação* - Crie um módulo raiz para a aplicação, cujo papel é: reunir todos os outros módulos e funcionalidades da sua aplicação. Nomeie ele de acordo com a sua aplicação. - **Por que?** Angular incentiva padrões de modularidade e de separação. Criando um módulo raiz da aplicação cujo papel é o de amarrar os outros módulos juntos, fica muito simples de adicionar ou remover módulos na sua aplicação. + **Por quê?** Angular incentiva padrões de modularidade e de separação. Criando um módulo raiz da aplicação cujo papel é o de amarrar os outros módulos juntos, fica muito simples de adicionar ou remover módulos na sua aplicação. ### Keep the App Module Thin ou *Mantenha o módulo da aplicação leve* - Somente coloque a lógica para reunir o aplicativo no módulo da aplicação. Deixe os recursos em seus próprios módulos. - **Por que?** Colocar funções adicionais na raiz da aplicação para obter dados remoto, modos de exibição, ou outra lógica não relacionada com o acoplamento do aplicativo, torna mais difícil reutilizar os recursos ou mesmo, desligá-los. + **Por quê?** Colocar funções adicionais na raiz da aplicação para obter dados remoto, modos de exibição, ou outra lógica não relacionada com o acoplamento do aplicativo, torna mais difícil reutilizar os recursos ou mesmo, desligá-los. - **Por que?** O módulo da aplicação torna-se um manifesto que descreve os módulos que ajudam a definir a aplicação. + **Por quê?** O módulo da aplicação torna-se um manifesto que descreve os módulos que ajudam a definir a aplicação. ### Feature Areas are Modules ou *Áreas de recursos são módulos* - Crie módulos que representem áreas de recursos, como: layout, serviços compartilhados e reutilizados, dashboards e recursos específicos do aplicativo (por exemplo, clientes, administrativo, vendas). - **Por que?** Módulos independentes podem ser adicionados na aplicação com pouco ou nenhum esforço. + **Por quê?** Módulos independentes podem ser adicionados na aplicação com pouco ou nenhum esforço. - **Por que?** Sprints ou iterações podem focar em áreas de recursos e acoplá-los na aplicação ao fim da sprint ou iteração. + **Por quê?** Sprints ou iterações podem focar em áreas de recursos e acoplá-los na aplicação ao fim da sprint ou iteração. **Por que²**: Separando as áreas de recursos em módulos, fica fácil de testar os módulos em isolamento e de reutilizar o código. @@ -2113,7 +2113,7 @@ ou *Blocos reutilizáveis são módulos* - Crie módulos que representam blocos reutilizáveis da aplicação para serviços comuns, como: tratamento de exceção, log, diagnósticos, segurança e armazenamento local. - **Por que?** Esses tipos de recursos são necessários em muitas aplicações, então mantê-los separados em seus próprios módulos os torna genéricos e assim, podem ser reutilizados em diferentes aplicações. + **Por quê?** Esses tipos de recursos são necessários em muitas aplicações, então mantê-los separados em seus próprios módulos os torna genéricos e assim, podem ser reutilizados em diferentes aplicações. ### Module Dependencies ou *Dependências do módulo* @@ -2122,11 +2122,11 @@ ou *Dependências do módulo* ![Moduluaridade e Dependências](https://raw.githubusercontent.com/johnpapa/angular-styleguide/master/a1/assets/modularity-1.png) - **Por que?** O módulo principal do aplicativo contém um rápido manifesto para identificar os recursos da aplicação. + **Por quê?** O módulo principal do aplicativo contém um rápido manifesto para identificar os recursos da aplicação. - **Por que?** Cada área de recurso contém um manifesto mostrando as suas dependências, assim, ela pode ser colocada como uma dependência em outras aplicação e ainda continuar funcionando. + **Por quê?** Cada área de recurso contém um manifesto mostrando as suas dependências, assim, ela pode ser colocada como uma dependência em outras aplicação e ainda continuar funcionando. - **Por que?** Recursos intra-aplicação como serviços compartilhados de dados, tornam-se muito mais fácil de localizar e compartilhar atráves do `app.core` (escolha o seu nome favorito para esse módulo). + **Por quê?** Recursos intra-aplicação como serviços compartilhados de dados, tornam-se muito mais fácil de localizar e compartilhar atráves do `app.core` (escolha o seu nome favorito para esse módulo). Nota: Essa é uma estratégia para consistência. Existem muitas outras boas opções. Escolha uma que seja consistente, que siga as regras de dependência do Angular, e que seja fácil de manter e escalar. @@ -2142,13 +2142,13 @@ ou *Dependências do módulo* - Use [`$document`](https://docs.angularjs.org/api/ng/service/$document) e [`$window`](https://docs.angularjs.org/api/ng/service/$window) ao invés de `document` e `window`. - **Por que?** Estes services são encapsulados pelo Angular e mais fáceis de testar do que o uso de document e window. Isso ajuda a evitar que você tenha que mockar document e window por sua própria conta. + **Por quê?** Estes services são encapsulados pelo Angular e mais fáceis de testar do que o uso de document e window. Isso ajuda a evitar que você tenha que mockar document e window por sua própria conta. ### $timeout e $interval - Use [`$timeout`](https://docs.angularjs.org/api/ng/service/$timeout) e [`$interval`](https://docs.angularjs.org/api/ng/service/$interval) ao invés de `setTimeout` e `setInterval` . - **Por que?** Estes services são encapsulados pelo Angular e mais fáceis de testar e lidar com o ciclo do AngularJS's mantendo o data binding em sincronismo. + **Por quê?** Estes services são encapsulados pelo Angular e mais fáceis de testar e lidar com o ciclo do AngularJS's mantendo o data binding em sincronismo. **[De volta ao topo](#tabela-de-conte%C3%BAdo)** @@ -2159,7 +2159,7 @@ Testes unitários ajudam a manter o código limpo, tal como, eu inclui algumas r - Escreva um grupo de testes para cada história. Comece com um teste em branco e preencha-o conforme você for escrevendo o código para a história. - **Por que?** Escrevendo uma descrição de teste te ajudará a definir claramente o que a sua história vai fazer ou não vai fazer e como você poderá mensurar o sucesso. + **Por quê?** Escrevendo uma descrição de teste te ajudará a definir claramente o que a sua história vai fazer ou não vai fazer e como você poderá mensurar o sucesso. ```javascript it('should have Avengers controller', function() { @@ -2185,7 +2185,7 @@ Testes unitários ajudam a manter o código limpo, tal como, eu inclui algumas r - Para teste unitários use [Jasmine](http://jasmine.github.io/) ou [Mocha](http://visionmedia.github.io/mocha/). - **Por que?** Ambos, Jasmine e Mocha são amplamente utilizados na comunidade AngularJS. Ambos são estáveis, são mantidos e provém features de teste robustas. + **Por quê?** Ambos, Jasmine e Mocha são amplamente utilizados na comunidade AngularJS. Ambos são estáveis, são mantidos e provém features de teste robustas. Nota: Se escolher Mocha, também considere a escolha de uma Assert Library como [Chai](http://chaijs.com). @@ -2193,27 +2193,27 @@ Testes unitários ajudam a manter o código limpo, tal como, eu inclui algumas r - Use [Karma](http://karma-runner.github.io) como seu test runner. - **Por que?** Karma é fácil de configurar para executar apenas uma vez ou automaticamente enquanto você altera seu código. + **Por quê?** Karma é fácil de configurar para executar apenas uma vez ou automaticamente enquanto você altera seu código. - **Por que?** Karma se integra facilmente com seu processo de Integração Contínua ou através do Grunt ou Gulp. + **Por quê?** Karma se integra facilmente com seu processo de Integração Contínua ou através do Grunt ou Gulp. - **Por que?** Algumas IDE's estão começando a se integrar com o Karma, como [WebStorm](http://www.jetbrains.com/webstorm/) e [Visual Studio](http://visualstudiogallery.msdn.microsoft.com/02f47876-0e7a-4f6c-93f8-1af5d5189225). + **Por quê?** Algumas IDE's estão começando a se integrar com o Karma, como [WebStorm](http://www.jetbrains.com/webstorm/) e [Visual Studio](http://visualstudiogallery.msdn.microsoft.com/02f47876-0e7a-4f6c-93f8-1af5d5189225). - **Por que?** Karma funciona muito bem com os líderes de automação de tarefas, como [Grunt](http://www.gruntjs.com) (com [grunt-karma](https://github.com/karma-runner/grunt-karma)) e [Gulp](http://www.gulpjs.com) (com [gulp-karma](https://github.com/lazd/gulp-karma)). + **Por quê?** Karma funciona muito bem com os líderes de automação de tarefas, como [Grunt](http://www.gruntjs.com) (com [grunt-karma](https://github.com/karma-runner/grunt-karma)) e [Gulp](http://www.gulpjs.com) (com [gulp-karma](https://github.com/lazd/gulp-karma)). ### Stubbing e Spying - Utilize Sinon para stubbing e spying. - **Por que?** Sinon funciona bem tanto com Jasmine quanto com Mocha e amplia as features de stubbing e spying que eles oferecem. + **Por quê?** Sinon funciona bem tanto com Jasmine quanto com Mocha e amplia as features de stubbing e spying que eles oferecem. - **Por que?** Sinon faz ficar mais fácil alternar entre Jasmine e Mocha, se você quiser tentar ambos. + **Por quê?** Sinon faz ficar mais fácil alternar entre Jasmine e Mocha, se você quiser tentar ambos. ### Headless Browser - Use [PhantomJS](http://phantomjs.org/) para executar seus testes no servidor. - **Por que?** PhantomJS é um headless browser que executa os testes sem um navegador "visual". Ou seja, você não precisa instalar Chrome, Safari, IE ou outros navegadores no seu servidor. + **Por quê?** PhantomJS é um headless browser que executa os testes sem um navegador "visual". Ou seja, você não precisa instalar Chrome, Safari, IE ou outros navegadores no seu servidor. Nota: Você deve continuar testando em todos os navegadores em seu ambiente, conforme apropriado para seu público alvo. @@ -2221,13 +2221,13 @@ Testes unitários ajudam a manter o código limpo, tal como, eu inclui algumas r - Execute JSHint no seus testes. - **Por que?** Testes são códigos. O JSHint ajuda a identificar problemas de qualidade de código que podem fazer com que o teste execute de maneira errada. + **Por quê?** Testes são códigos. O JSHint ajuda a identificar problemas de qualidade de código que podem fazer com que o teste execute de maneira errada. ### Ignore algumas regras globais do JSHint no seus testes - Faça com que as regras de teste permitam globais comuns, tais como `describe` e `expect`. - **Por que?** Seus testes são codigos e como tal necessitam da mesma atenção e regras de qualidade que todo o seu código de produção. No entanto, as variáveis globais usadas pelo framework de teste, por exemplo, podem ser ignoradas para que você as utilize em seus testes. + **Por quê?** Seus testes são codigos e como tal necessitam da mesma atenção e regras de qualidade que todo o seu código de produção. No entanto, as variáveis globais usadas pelo framework de teste, por exemplo, podem ser ignoradas para que você as utilize em seus testes. ```javascript /* global sinon, describe, it, afterEach, beforeEach, expect, inject */ @@ -2244,25 +2244,25 @@ ou *Animações* - Use [animações com AngularJS](https://docs.angularjs.org/guide/animations) para transitar suavemente entre a visualização de views e elementos visuais primários. Inclúa o módulo [ngAnimate](https://docs.angularjs.org/api/ngAnimate). Os três princípios são sutilidade, suavidade e sem remendos. - **Por que?** Animações sutis podem melhorar a Experiência de Usuário (UX) quando usadas adequadamente. + **Por quê?** Animações sutis podem melhorar a Experiência de Usuário (UX) quando usadas adequadamente. - **Por que?** Animações sutis podem aumentar a sensação de performance durante a alteração entre views. + **Por quê?** Animações sutis podem aumentar a sensação de performance durante a alteração entre views. ### Sub Second - Use animações de curta duração. Eu geralmente começo com 300ms e ajusto conforme necessário. - **Por que?** Animações de longa duração podem impactar negativamente na experiência do usuário e em sua percepção de desempenho, dando a impressão de ser uma aplicação lenta. + **Por quê?** Animações de longa duração podem impactar negativamente na experiência do usuário e em sua percepção de desempenho, dando a impressão de ser uma aplicação lenta. ### animate.css - Use [animate.css](http://daneden.github.io/animate.css/) para animações convencionais. - **Por que?** As animações fornecidas por animate.css são rápidas, suaves e fáceis de adicionar à sua aplicação. + **Por quê?** As animações fornecidas por animate.css são rápidas, suaves e fáceis de adicionar à sua aplicação. - **Por que?** Provê consistência em suas animações. + **Por quê?** Provê consistência em suas animações. - **Por que?** animate.css amplamente utilizado e testado. + **Por quê?** animate.css amplamente utilizado e testado. Nota: Leia este [excelente post do Matias Niemelä sobre Angular Animations](http://www.yearofmoo.com/2013/08/remastered-animation-in-angularjs-1-2.html) @@ -2275,9 +2275,9 @@ ou *Comentários* - Se você planeja produzir documentação, use a sintaxe [`jsDoc`](http://usejsdoc.org/) para documentar nomes, descrições, parâmetros e retornos de funções. Use `@namespace` e `@memberOf` para adequar à estrutura de sua aplicação. - **Por que?** Você pode gerar (e regerar) documentação a partir do seu código ao invés de escrever do zero. + **Por quê?** Você pode gerar (e regerar) documentação a partir do seu código ao invés de escrever do zero. - **Por que?** Fornece consistência utilizando uma ferramenta comum no mercado. + **Por quê?** Fornece consistência utilizando uma ferramenta comum no mercado. ```javascript /** @@ -2326,9 +2326,9 @@ ou *Comentários* - Use JS Hint para inspecionar seu JavaScript e não se esqueça de customizar o arquivo de configurações e versioná-lo no controle de versão. Veja [JS Hint docs](http://www.jshint.com/docs/) para detalhes a respeito das opções. - **Por que?** Fornece um primeiro alerta antes de commitar qualquer código ao controle de versão. + **Por quê?** Fornece um primeiro alerta antes de commitar qualquer código ao controle de versão. - **Por que?** Provê consistência a seu time. + **Por quê?** Provê consistência a seu time. ```javascript { @@ -2404,7 +2404,7 @@ ou *Comentários* - Cria uma *Constant* no Angular para variáveis globais de bibliotecas de terceiros. - **Por que?** Fornece uma forma de injetar bibliotecas de terceiros que de outra forma seriam globais. Isso melhora a testabilidade do código permitindo a você conhecer mais facilmente quais dependências os seus componentes têm (evita vazamento de abstrações). Também permite que você simule estas dependências, o que faz sentido. + **Por quê?** Fornece uma forma de injetar bibliotecas de terceiros que de outra forma seriam globais. Isso melhora a testabilidade do código permitindo a você conhecer mais facilmente quais dependências os seus componentes têm (evita vazamento de abstrações). Também permite que você simule estas dependências, o que faz sentido. ```javascript // constants.js From 573624fc3acacf7fa466cae2caca893860cb953f Mon Sep 17 00:00:00 2001 From: Bruno Dulcetti Date: Wed, 6 Dec 2017 10:52:21 -0200 Subject: [PATCH 2/2] Portuguese corrections inside verbs and gerund --- a1/i18n/pt-BR.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/a1/i18n/pt-BR.md b/a1/i18n/pt-BR.md index a57876ef..fbc19eac 100644 --- a/a1/i18n/pt-BR.md +++ b/a1/i18n/pt-BR.md @@ -469,7 +469,7 @@ ou *Controladores* ### Function Declarations to Hide Implementation Details - - Utilize declarações de funções para esconder detalhes de implementação. Mantenha seus objetos que necessitam de bind no topo. Quando você precisar fazer o bind de uma função no controller, aponte ela para a declaração de função que aparece no final do arquivo. Ela está ligada diretamente aos objetos que precisam de bind no início do arquivo. Para mais detalhes veja [este post](http://www.johnpapa.net/angular-function-declarations-function-expressions-and-readable-code). + - Utilize declarações de funções para esconder detalhes de implementação. Mantenha seus objetos que necessitam de bind no topo. Quando você precisar fazer o bind de uma função no controller, aponte-a para a declaração de função que aparece no final do arquivo. Ela está ligada diretamente aos objetos que precisam de bind no início do arquivo. Para mais detalhes veja [este post](http://www.johnpapa.net/angular-function-declarations-function-expressions-and-readable-code). **Por quê?** Colocar os objetos que precisam de bind no início torna mais fácil de ler e te ajuda a instantaneamente identificar quais objetos do controller podem ser utilizados na View. (Mesmo do item anterior.) @@ -543,7 +543,7 @@ ou *Controladores* ### Defer Controller Logic - - Remova a lógica do controller delegando ela a services e factories. + - Remova a lógica do controller delegando-na a services e factories. **Por quê?** A lógica pode ser reutilizada em múltiplos controllers quando colocada em um service e exposta através de uma função.