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

[yuriwithowsky]

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

[github-actions]

Thanks for the PR!

This section of the codebase is owned by @khaosdoctor and @danilofuchs - if they write a comment saying "LGTM" then it will be merged.

[github-actions]

Translation of Do's and Don'ts.md

---

title: Standards
layout: docs
permalink: /pt/docs/handbook/declaration-files/do-s-and-don-ts.html

oneline: "Recommendations for writing d.ts files"

General Types

Number, String, Boolean, Symbol And Object

❌ Never use the types Number, String, Boolean, Symbolor Object
These types reference non-primitive objects that are almost never used appropriately in JavaScript code.

/* Errado */
function reverte(s: String): String;

✅ Always use the types number, string, booleanand symbol.

/* OK */
function reverte(s: string): string;

Instead of Object, use the non-primitive type object (added in TypeScript 2.2).

Generics

❌ Never have a generic type that does not use the types of its parameters.
See more details at TypeScript FAQ page.

Any any

❌ Never Use any as type unless you are in the process of migrating the javascript project to Typescript. The compiler effectively Comes any like "please turn off the type check for this thing". This is similar to putting a comment @ts-ignore around each use of the variable. This can be very useful when you are first migrating a JavaScript project to TypeScript because you can set the type for things you haven't migrated as any, but in a full TypeScript project you will be disabling type checking for any part of your program that uses it.

In cases where you don't know the type you want to accept, or when you want to accept anything because it will go on blindly without interacting, you can use unknown.

Callback Types

Return Types and Callbacks

❌ Never use the return type any for callbacks whose value will be ignored:

/* ERRADO */
function fn(x: () => any) {
  x();
}

✅ Always use the return type void for callbacks whose value will be ignored:

/* OK */
function fn(x: () => void) {
  x();
}

❔ Why is that?: Using void is safer because it prevents you from accidentally using the return value of x in an unverified manner:

function fn(x: () => void) {
  var k = x(); // oops! deveria fazer outra coisa
  k.facaAlgo(); // erro, mas ficaria OK se o tipo retorno tivesse sido 'any'
}

Optional Parameters in Callbacks

❌ Never use optional parameters on callbacks unless you actually have this intent:

/* ERRADO */
interface Buscador {
  retornaObjeto(pronto: (data: any, tempoDecorrido?: number) => void): void;
}

This has a very specific meaning: the callback pronto can be invoked with 1 argument or can be invoked with 2 arguments.
The author probably intended to say that the callback might not care about the parameter tempoDecorrido, but you don't need to do the optional parameter to achieve this --
it is always valid to provide a callback that accepts a smaller number of arguments.

✅ Always write callback parameters as non-optional:

/* OK */
interface Buscador {
  retornaObjeto(pronto: (data: any, tempoDecorrido: number) => void): void;
}

Overloads and Callbacks

❌ Never write separate overloads that differ only in the arity of the callback:

/* ERRADO */
declare function antesDeTodos(acao: () => void, timeout?: number): void;
declare function antesDeTodos(
  acao: (done: DoneFn) => void,
  timeout?: number
): void;

✅ Always write a single overload using the maximum arity:

/* OK */
declare function antesDeTodos(
  acao: (done: DoneFn) => void,
  timeout?: number
): void;

❔ Why is that?: It is always valid for a callback to disregard a parameter, so there is no need to shorten the overhead.
Providing a shorter callback first allows incorrectly typed functions to be passed forward because they match the first overload.

Function Overloads

Ordination

❌ Never put mental overloads before the most specific:

/* ERRADO */
declare function fn(x: any): any;
declare function fn(x: HTMLElement): number;
declare function fn(x: HTMLDivElement): string;

var meuElem: HTMLDivElement;
var x = fn(meuElem); // x: any, quê?

✅ Always order overloads by placing the most generic signatures after the most specific ones:

/* OK */
declare function fn(x: HTMLDivElement): string;
declare function fn(x: HTMLElement): number;
declare function fn(x: any): any;

var meuElem: HTMLDivElement;
var x = fn(meuElem); // x: string, :)

❔ Why is that?: TypeScript chooses the first overload with matching when resolving calls to functions.
When a newer overload "is more general" than an older one, the oldest one is effectively omitted and cannot be called.

Use Optional Parameters

❌ Never write many overloads that differ only in the final parameters:

/* ERRADO */
interface Exemplo {
  diff(um: string): number;
  diff(um: string, dois: string): number;
  diff(um: string, dois: string, tres: boolean): number;
}

✅ Always optional parameters:

/* OK */
interface Exemplo {
  diff(um: string, dois?: string, tres?: boolean): number;
}

Note that this collapse should occur only when all overloads have the same return type.

❔ Why is that?: This is important for two reasons.

TypeScript resolves signature compatibility by verifying that any target signatures can be called with the source arguments,and strange arguments are allowed.
This code, for example, exposes a bug only when the signature is written correctly using optional parameters:

function fn(x: (a: string, b: number, c: number) => void) {}
var x: Exemplo;
// Quando escrito com sobrecarga, OK -- usado a primeira sobrecarga
// Quando escrito com opcionais, devidamente um erro
fn(x.diff);

The second reason is when a consumer uses TypeScript's "strict null checking" functionality.
Because unspecified parameters appear as undefined in javascript, it's usually good to spend a undefined for a function with optional arguments.
This code, for example, should be OK under strict nulls:

var x: Exemplo;
// Quando escrito com sobrecargas,  um erro porque passa 'undefined' para 'string'
// Quando escrito com opcionais, devidamente OK
x.diff("algo", true ? undefined : "hora");

Use Union Types

❌ Never write overloads that differ by type in just one argument:

/* ERRADO */
interface Momento {
  utcOffset(): number;
  utcOffset(b: number): Momento;
  utcOffset(b: string): Momento;
}

✅ Always possible to use union types:

/* OK */
interface Momento {
  utcOffset(): number;
  utcOffset(b: number | string): Momento;
}

Realize we didn't b optional here because the return types of signatures are different.
❔ Why is that?: This is important for people who are "passing on" a value for their role:

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, devidamente OK
  return momento().utcOffset(x);
}

Generated by 🚫 dangerJS against 795d30d

[khaosdoctor]

LGTM

[khaosdoctor]

LGTM?

[yuriwithowsky]

LGTM?

The merge-check job failed 😞

[github-actions]

Sorry @yuriwithowsky, you don't have access to these files:

• /docs/documentation/pt/declaration-files/Do's and Don'ts.md.

[khaosdoctor]

Apparently the integration cannot access the file, @orta do you still have access to these integrations?

[orta]

it's pretty arbitrary - sometime it just requires re-asking OSS-Docs-Tools/code-owner-self-merge#35