diff --git a/docs/documentation/pt/declaration-files/Do's and Don'ts.md b/docs/documentation/pt/declaration-files/Do's and Don'ts.md index 8c15c26c..8a1c59f1 100644 --- a/docs/documentation/pt/declaration-files/Do's and Don'ts.md +++ b/docs/documentation/pt/declaration-files/Do's and Don'ts.md @@ -1,5 +1,5 @@ --- -title: Do's and Don'ts +title: Normas layout: docs permalink: /pt/docs/handbook/declaration-files/do-s-and-don-ts.html oneline: "Recomendações para escrita de arquivos d.ts" @@ -9,7 +9,7 @@ oneline: "Recomendações para escrita de arquivos d.ts" ## `Number`, `String`, `Boolean`, `Symbol` and `Object` -_Nunca_ use os tipos `Number`, `String`, `Boolean`, `Symbol`, ou `Object` +❌ _Nunca_ use os tipos `Number`, `String`, `Boolean`, `Symbol`, ou `Object` Esse tipos fazem referências a objetos não-primitivos que quase nunca são usados apropriadamente em códigos JavaScript. ```ts @@ -17,7 +17,7 @@ Esse tipos fazem referências a objetos não-primitivos que quase nunca são usa function reverte(s: String): String; ``` -_Sempre_ use os tipos `number`, `string`, `boolean`, e `symbol`. +✅ _Sempre_ use os tipos `number`, `string`, `boolean`, e `symbol`. ```ts /* OK */ @@ -28,16 +28,15 @@ Ao invés de `Object`, use o tipo não-primitivo `object` ([adicionado em TypeSc ## Generics -_Nunca_ tenha um tipo genérico que não use os tipos de seus parâmetros. +❌ _Nunca_ tenha um tipo genérico que não use os tipos de seus parâmetros. Veja mais detalhes em [TypeScript FAQ page](https://github.com/Microsoft/TypeScript/wiki/FAQ#why-doesnt-type-inference-work-on-this-interface-interface-foot--). ## any -_Nunca_ use `any` como tipo a não ser que você esteja no processo de migração do projeto de JavaScript para Typescript. O compilador _efetivamente_ trata `any` como "por favor desligue a verificação de tipo para essa coisa". Isso é similar a botar um comentário `@ts-ignore` em volta de cada uso da variável. Isso pode ser muito útil quando você está migrando pela primeira vez um projeto JavaScript para TypeScript pois pode definir o tipo para coisas que você ainda não migrou como `any`, mas em um projeto TypeScript completo você estará desabilitando a verificação de tipos para qualquer parte do seu programa que o use. +❌ _Nunca_ use `any` como tipo a não ser que você esteja no processo de migração do projeto de JavaScript para Typescript. O compilador _efetivamente_ trata `any` como "por favor desligue a verificação de tipo para essa coisa". Isso é similar a botar um comentário `@ts-ignore` em volta de cada uso da variável. Isso pode ser muito útil quando você está migrando pela primeira vez um projeto JavaScript para TypeScript pois pode definir o tipo para coisas que você ainda não migrou como `any`, mas em um projeto TypeScript completo você estará desabilitando a verificação de tipos para qualquer parte do seu programa que o use. Em casos onde você não sabe o tipo você quer aceitar, ou quando quer aceitar qualquer coisa pois irá passar adiante cegamente sem interagir, você pode usar [`unknown`](/play/#example/unknown-and-never). - ## Tipos de Callback @@ -46,7 +45,7 @@ Em casos onde você não sabe o tipo você quer aceitar, ou quando quer aceitar -_Nunca_ use o tipo de retorno `any` para callbacks cujo o valor será ignorado: +❌ _Nunca_ use o tipo de retorno `any` para callbacks cujo o valor será ignorado: ```ts /* ERRADO */ @@ -55,7 +54,7 @@ function fn(x: () => any) { } ``` -_Sempre_ use o tipo de retorno `void` para callbacks cujo o valor será ignorado: +✅ _Sempre_ use o tipo de retorno `void` para callbacks cujo o valor será ignorado: ```ts /* OK */ @@ -64,7 +63,7 @@ function fn(x: () => void) { } ``` -_Por quê?_: Usar void é mais seguro porque te previne de acidentalmente usar o valor de retorno de `x` de forma não verificada: +❔ _Por quê?_: Usar void é mais seguro porque te previne de acidentalmente usar o valor de retorno de `x` de forma não verificada: ```ts function fn(x: () => void) { @@ -75,7 +74,7 @@ function fn(x: () => void) { ## Parâmetros Opcionais em Callbacks -_Nunca_ use parâmetros opcionais em callbacks a não ser que você realmente tenha essa intenção: +❌ _Nunca_ use parâmetros opcionais em callbacks a não ser que você realmente tenha essa intenção: ```ts /* ERRADO */ @@ -85,10 +84,10 @@ interface Buscador { ``` Isso tem um significado muito especifico: o callback `pronto` pode ser invocado com 1 argumento ou pode ser invocado com 2 argumentos. -O autor provavelmente teve a intenção de dizer que o callback talvez não se importe com o parâmetro `tempoDecorrido`, mas não tem necessidade de fazer o parâmetro opcional para atingir isso -- +O autor provavelmente teve a intenção de dizer que o callback talvez não se importe com o parâmetro `tempoDecorrido`, mas não tem necessidade de fazer o parâmetro opcional para atingir isso -- sempre é valido prover um callback que aceita um numero menor de argumentos. -_Sempre_ escreva parâmetros de callback como não-opcional: +✅ _Sempre_ escreva parâmetros de callback como não-opcional: ```ts /* OK */ @@ -99,7 +98,7 @@ interface Buscador { ## Sobrecargas e Callbacks -_Nunca_ escreva sobrecargas separadas que diferem apenas na aridade do callback: +❌ _Nunca_ escreva sobrecargas separadas que diferem apenas na aridade do callback: ```ts /* ERRADO */ @@ -110,7 +109,7 @@ declare function antesDeTodos( ): void; ``` -_Sempre_ escreva uma única sobrecarga usando a aridade maxima: +✅ _Sempre_ escreva uma única sobrecarga usando a aridade maxima: ```ts /* OK */ @@ -120,14 +119,14 @@ declare function antesDeTodos( ): void; ``` -_Por quê?_: Sempre é válido para um callback desprezar um parâmetro, então não tem necessidade de encurtar a sobrecarga. +❔ _Por quê?_: Sempre é válido para um callback desprezar um parâmetro, então não tem necessidade de encurtar a sobrecarga. Provendo um callback mais curto primeiro permite funções incorretamente tipadas serem passadas adiante porque possuem correspondência com a primeira sobrecarga. ## Sobrecargas de Funções ## Ordenação -_Nunca_ ponha sobrecargas genérias antes das mais específicas: +❌ _Nunca_ ponha sobrecargas genérias antes das mais específicas: ```ts /* ERRADO */ @@ -139,7 +138,7 @@ var meuElem: HTMLDivElement; var x = fn(meuElem); // x: any, quê? ``` -_Sempre_ ordene sobrecargas pondo as assinaturas mais genéricas após as mais específicas: +✅ _Sempre_ ordene sobrecargas pondo as assinaturas mais genéricas após as mais específicas: ```ts /* OK */ @@ -151,12 +150,12 @@ var meuElem: HTMLDivElement; var x = fn(meuElem); // x: string, :) ``` -_Por quê?_: TypeScript escolhe a _primeira sobrecarga com correspondência_ ao resolver chamadas as funções. -Quando uma sobrecarga mais recente "é mais geral" do que uma mais antiga, a mais antiga é efetivamente omitida e não pode ser chamada. +❔ _Por quê?_: TypeScript escolhe a _primeira sobrecarga com correspondência_ ao resolver chamadas as funções. +Quando uma sobrecarga mais recente "é mais geral" do que uma mais antiga, a mais antiga é efetivamente omitida e não pode ser chamada. ## Use Parâmetros Opcionais -_Nunca_ escreva muitas sobrecargas que diferem apenas em nos parâmetros finais: +❌ _Nunca_ escreva muitas sobrecargas que diferem apenas em nos parâmetros finais: ```ts /* ERRADO */ @@ -167,7 +166,7 @@ interface Exemplo { } ``` -_Sempre_ que possível use parâmetros opcionais: +✅ _Sempre_ que possível use parâmetros opcionais: ```ts /* OK */ @@ -178,11 +177,10 @@ interface Exemplo { Note que esse colapso deve ocorrer apenas quando todas as sobrecargas tiverem o mesmo tipo de retorno. - -_Por quê?_: Isso é importante por dois motivos. +❔ _Por quê?_: Isso é importante por dois motivos. TypeScript resolve compatibilidade de assinaturas verificando se alguma assinatura do alvo pode ser chamada com os argumentos da fonte,_e argumentos estranhos são permitidos_. -Esse código, por exemplo, expõe um bug apenas quando a assinatura é escrita corretamente usando parâmetros opcionais: +Esse código, por exemplo, expõe um bug apenas quando a assinatura é escrita corretamente usando parâmetros opcionais: ```ts function fn(x: (a: string, b: number, c: number) => void) {} @@ -193,7 +191,7 @@ fn(x.diff); ``` A segunda razão é quando um consumidor usa a funcionalidade "checagem estrita de nulos" do TypeScript. -Porque parâmetros não especificados aparecem como `undefined` em javascript, geralmente é bom passar um `undefined` explícito para uma função com argumentos opcionais. +Porque parâmetros não especificados aparecem como `undefined` em javascript, geralmente é bom passar um `undefined` explícito para uma função com argumentos opcionais. Esse código, por exemplo, deveria ser OK sob nulos estritos: ```ts @@ -205,7 +203,7 @@ x.diff("algo", true ? undefined : "hora"); ## Use Tipos de União -_Nunca_ escreva sobrecargas que diferem por tipo em apenas um argumento: +❌ _Nunca_ escreva sobrecargas que diferem por tipo em apenas um argumento: ```ts /* ERRADO */ @@ -216,7 +214,7 @@ interface Momento { } ``` -_Sempre_ que possível use tipos de união: +✅ _Sempre_ que possível use tipos de união: ```ts /* OK */ @@ -227,15 +225,14 @@ interface Momento { ``` Perceba que nós não fizemos `b` opcional aqui porque os tipos de retorno das assinaturas são diferentes. -_Por quê?_: Isso é importante para pessoas que estão "passando adiante" um valor para sua função: +❔ _Por quê?_: Isso é importante para pessoas que estão "passando adiante" um valor para sua função: ```ts function fn(x: string): void; function fn(x: number): void; function fn(x: number | string) { // Quando escrito com sobrecargas separadas, indevidamente um erro - // Quando escrito com tipos de união, - // When written with union types, devidamente OK + // Quando escrito com tipos de união, devidamente OK return momento().utcOffset(x); } ```