Skip to content

fix(do's and dont's): add emojis as in english doc and fix translation #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix(do's and dont's): add emojis as in english doc and fix translation #178

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 27 additions & 30 deletions docs/documentation/pt/declaration-files/Do's and Don'ts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
Expand All @@ -9,15 +9,15 @@ 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
/* Errado */
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 */
Expand All @@ -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).


<!-- TODO: More -->

## Tipos de Callback
Expand All @@ -46,7 +45,7 @@ Em casos onde você não sabe o tipo você quer aceitar, ou quando quer aceitar

<!-- TODO: Reword; these examples make no sense in the context of a declaration file -->

_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 */
Expand All @@ -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 */
Expand All @@ -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) {
Expand All @@ -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 */
Expand All @@ -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 */
Expand All @@ -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 */
Expand All @@ -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 */
Expand All @@ -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 */
Expand All @@ -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 */
Expand All @@ -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 */
Expand All @@ -167,7 +166,7 @@ interface Exemplo {
}
```

_Sempre_ que possível use parâmetros opcionais:
✅ _Sempre_ que possível use parâmetros opcionais:

```ts
/* OK */
Expand All @@ -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) {}
Expand All @@ -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
Expand All @@ -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 */
Expand All @@ -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 */
Expand All @@ -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);
}
```