You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
oneline: "Recomendações para escrita de arquivos d.ts"
@@ -9,15 +9,15 @@ oneline: "Recomendações para escrita de arquivos d.ts"
9
9
10
10
## `Number`, `String`, `Boolean`, `Symbol` and `Object`
11
11
12
-
_Nunca_ use os tipos `Number`, `String`, `Boolean`, `Symbol`, ou `Object`
12
+
❌ _Nunca_ use os tipos `Number`, `String`, `Boolean`, `Symbol`, ou `Object`
13
13
Esse tipos fazem referências a objetos não-primitivos que quase nunca são usados apropriadamente em códigos JavaScript.
14
14
15
15
```ts
16
16
/* Errado */
17
17
function reverte(s:String):String;
18
18
```
19
19
20
-
_Sempre_ use os tipos `number`, `string`, `boolean`, e `symbol`.
20
+
✅ _Sempre_ use os tipos `number`, `string`, `boolean`, e `symbol`.
21
21
22
22
```ts
23
23
/* OK */
@@ -28,16 +28,15 @@ Ao invés de `Object`, use o tipo não-primitivo `object` ([adicionado em TypeSc
28
28
29
29
## Generics
30
30
31
-
_Nunca_ tenha um tipo genérico que não use os tipos de seus parâmetros.
31
+
❌ _Nunca_ tenha um tipo genérico que não use os tipos de seus parâmetros.
32
32
Veja mais detalhes em [TypeScript FAQ page](https://github.com/Microsoft/TypeScript/wiki/FAQ#why-doesnt-type-inference-work-on-this-interface-interface-foot--).
33
33
34
34
## any
35
35
36
-
_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.
36
+
❌ _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.
37
37
38
38
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).
39
39
40
-
41
40
<!-- TODO: More -->
42
41
43
42
## Tipos de Callback
@@ -46,7 +45,7 @@ Em casos onde você não sabe o tipo você quer aceitar, ou quando quer aceitar
46
45
47
46
<!-- TODO: Reword; these examples make no sense in the context of a declaration file -->
48
47
49
-
_Nunca_ use o tipo de retorno `any` para callbacks cujo o valor será ignorado:
48
+
❌ _Nunca_ use o tipo de retorno `any` para callbacks cujo o valor será ignorado:
50
49
51
50
```ts
52
51
/* ERRADO */
@@ -55,7 +54,7 @@ function fn(x: () => any) {
55
54
}
56
55
```
57
56
58
-
_Sempre_ use o tipo de retorno `void` para callbacks cujo o valor será ignorado:
57
+
✅ _Sempre_ use o tipo de retorno `void` para callbacks cujo o valor será ignorado:
59
58
60
59
```ts
61
60
/* OK */
@@ -64,7 +63,7 @@ function fn(x: () => void) {
64
63
}
65
64
```
66
65
67
-
_Por quê?_: Usar void é mais seguro porque te previne de acidentalmente usar o valor de retorno de `x` de forma não verificada:
66
+
❔ _Por quê?_: Usar void é mais seguro porque te previne de acidentalmente usar o valor de retorno de `x` de forma não verificada:
68
67
69
68
```ts
70
69
function fn(x: () =>void) {
@@ -75,7 +74,7 @@ function fn(x: () => void) {
75
74
76
75
## Parâmetros Opcionais em Callbacks
77
76
78
-
_Nunca_ use parâmetros opcionais em callbacks a não ser que você realmente tenha essa intenção:
77
+
❌ _Nunca_ use parâmetros opcionais em callbacks a não ser que você realmente tenha essa intenção:
79
78
80
79
```ts
81
80
/* ERRADO */
@@ -85,10 +84,10 @@ interface Buscador {
85
84
```
86
85
87
86
Isso tem um significado muito especifico: o callback `pronto` pode ser invocado com 1 argumento ou pode ser invocado com 2 argumentos.
88
-
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 --
87
+
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 --
89
88
sempre é valido prover um callback que aceita um numero menor de argumentos.
90
89
91
-
_Sempre_ escreva parâmetros de callback como não-opcional:
90
+
✅ _Sempre_ escreva parâmetros de callback como não-opcional:
92
91
93
92
```ts
94
93
/* OK */
@@ -99,7 +98,7 @@ interface Buscador {
99
98
100
99
## Sobrecargas e Callbacks
101
100
102
-
_Nunca_ escreva sobrecargas separadas que diferem apenas na aridade do callback:
101
+
❌ _Nunca_ escreva sobrecargas separadas que diferem apenas na aridade do callback:
103
102
104
103
```ts
105
104
/* ERRADO */
@@ -110,7 +109,7 @@ declare function antesDeTodos(
110
109
):void;
111
110
```
112
111
113
-
_Sempre_ escreva uma única sobrecarga usando a aridade maxima:
112
+
✅ _Sempre_ escreva uma única sobrecarga usando a aridade maxima:
114
113
115
114
```ts
116
115
/* OK */
@@ -120,14 +119,14 @@ declare function antesDeTodos(
120
119
):void;
121
120
```
122
121
123
-
_Por quê?_: Sempre é válido para um callback desprezar um parâmetro, então não tem necessidade de encurtar a sobrecarga.
122
+
❔ _Por quê?_: Sempre é válido para um callback desprezar um parâmetro, então não tem necessidade de encurtar a sobrecarga.
124
123
Provendo um callback mais curto primeiro permite funções incorretamente tipadas serem passadas adiante porque possuem correspondência com a primeira sobrecarga.
125
124
126
125
## Sobrecargas de Funções
127
126
128
127
## Ordenação
129
128
130
-
_Nunca_ ponha sobrecargas genérias antes das mais específicas:
129
+
❌ _Nunca_ ponha sobrecargas genérias antes das mais específicas:
131
130
132
131
```ts
133
132
/* ERRADO */
@@ -139,7 +138,7 @@ var meuElem: HTMLDivElement;
139
138
var x =fn(meuElem); // x: any, quê?
140
139
```
141
140
142
-
_Sempre_ ordene sobrecargas pondo as assinaturas mais genéricas após as mais específicas:
141
+
✅ _Sempre_ ordene sobrecargas pondo as assinaturas mais genéricas após as mais específicas:
143
142
144
143
```ts
145
144
/* OK */
@@ -151,12 +150,12 @@ var meuElem: HTMLDivElement;
151
150
var x =fn(meuElem); // x: string, :)
152
151
```
153
152
154
-
_Por quê?_: TypeScript escolhe a _primeira sobrecarga com correspondência_ ao resolver chamadas as funções.
155
-
Quando uma sobrecarga mais recente "é mais geral" do que uma mais antiga, a mais antiga é efetivamente omitida e não pode ser chamada.
153
+
❔ _Por quê?_: TypeScript escolhe a _primeira sobrecarga com correspondência_ ao resolver chamadas as funções.
154
+
Quando uma sobrecarga mais recente "é mais geral" do que uma mais antiga, a mais antiga é efetivamente omitida e não pode ser chamada.
156
155
157
156
## Use Parâmetros Opcionais
158
157
159
-
_Nunca_ escreva muitas sobrecargas que diferem apenas em nos parâmetros finais:
158
+
❌ _Nunca_ escreva muitas sobrecargas que diferem apenas em nos parâmetros finais:
160
159
161
160
```ts
162
161
/* ERRADO */
@@ -167,7 +166,7 @@ interface Exemplo {
167
166
}
168
167
```
169
168
170
-
_Sempre_ que possível use parâmetros opcionais:
169
+
✅ _Sempre_ que possível use parâmetros opcionais:
171
170
172
171
```ts
173
172
/* OK */
@@ -178,11 +177,10 @@ interface Exemplo {
178
177
179
178
Note que esse colapso deve ocorrer apenas quando todas as sobrecargas tiverem o mesmo tipo de retorno.
180
179
181
-
182
-
_Por quê?_: Isso é importante por dois motivos.
180
+
❔ _Por quê?_: Isso é importante por dois motivos.
183
181
184
182
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_.
185
-
Esse código, por exemplo, expõe um bug apenas quando a assinatura é escrita corretamente usando parâmetros opcionais:
183
+
Esse código, por exemplo, expõe um bug apenas quando a assinatura é escrita corretamente usando parâmetros opcionais:
186
184
187
185
```ts
188
186
function fn(x: (a:string, b:number, c:number) =>void) {}
@@ -193,7 +191,7 @@ fn(x.diff);
193
191
```
194
192
195
193
A segunda razão é quando um consumidor usa a funcionalidade "checagem estrita de nulos" do TypeScript.
196
-
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.
194
+
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.
197
195
Esse código, por exemplo, deveria ser OK sob nulos estritos:
0 commit comments