Skip to content

Latest commit

 

History

History
146 lines (118 loc) · 5.83 KB

guia-de-estilo.adoc

File metadata and controls

146 lines (118 loc) · 5.83 KB
Raw

Guia de Estilo

Seções

Padrões gráficos e de linguagem adotados nesta tradução.

1. Termos adotados

Os termos abaixo geram dúvidas sobre tradução: se devem ser traduzidos ou não, e qual tradução adotar. Estas foram as decisões que tomamos nesta tradução.

Quando o termo em inglês for adotado, faremos uma opção de gênero do substantivo. Ex.: o framework (s.m.), a thread (s.f.)

A opção será subjetiva, baseada no uso cotidiano na bolha dev ao redor do autor. Para manter a consistência, a opção de gênero está registrada nos termos adotados em inglês na tabela.

Sempre que um desses termos aparecer pela primeira vez no livro, o termo adotado deve ser seguido da alternativa no outro idioma, para familiarizar a leitora com o vocabulário nos dois idiomas.

O termo em inglês deve ser sempre escrito em itálico. Se houver parênteses em torno do termo em inglês, o parênteses também deve estar em itálico (italic).

Exemplos:

Termo em português adotado

embutido (built-in)

Termo em inglês adotado

o cluster (agrupamento)

Legenda

✅

termo adotado

❗

termo não adotado

❓

não conhecemos uma boa tradução

🔎

possíveis ocorrências para buscar e corrigir

🇺🇸

🇧🇷

Observações

❗ abstract base class

✅ classe base abstrata

plural: classes bases abstratas

✅ alias (s.m.)

❗ apelido

✅ aliasing (s.m.)

❗ apelidamento

✅ array (s.m.)

❗ arranjo

🔎 a array

❗ built-in

✅ embutido

✅ cache (s.m.)

❓

✅ caching (s.m.)

❓

❗ callable

✅ invocável (s.m.)

🔎 chamável

✅ callback (s.f.)

❗ função que trata o evento

🔎 função de retorno

❗ closure

✅ clausura

preserva variáveis livres no momento da definição da função

✅ cluster (s.m.)

❓

🔎 agrupamento

❗ container

✅ o contêiner

plural: contêineres

❗ contention

✅ disputa

❗ core

✅ núcleo

"CPU de 8 núcleos"

❗ coroutine

✅ corrotina

❗ CPU bound

✅ limitado pela CPU

✅ deadlock (s.m.)

❗ impasse

❗ duck typing

✅ tipagem pato

❗ evaluate

✅ avaliar

contraste com "analisar" (parse)

❗ evaluation

✅ avaliação

❗ factory

✅ fábrica

✅ framework (s.m.)

❗ arcabouço

🔎 a framework

❗ Further Reading

✅ Para saber mais

título de seção (note: apenas 1ª letra maiúscula)

✅ future (s.m.)

❓

❗ goose typing

✅ tipagem ganso

✅ hashable (adj.)

❓

✅ hook (s.m.)

❗gancho

❗ I/O bound

✅ limitado por E/S

❗ keyword argument

✅ argumento nomeado

🔎 argumento de palavra-chave

❗ lock

✅ trava

❗ match (s.m.)

✅ casamento

substantivo; aplica-se a match/case e re.match

❗ match (v.)

✅ casar

verbo; aplica-se a match/case e re.match

✅ offset (s.m.)

❗ deslocamento

🔎 a offset

❗ overloading

✅ sobrecarga

❗ overloaded signatures

✅ assinaturas sobrecarregadas

❗ parse

✅ analise (ou análise sintática)

contraste com "avaliar" (evaluate)

✅ parser (s.m.)

❗ analisador sintático

🔎 a parser

❗ pattern

✅ padrão

aplica-se a match/case e re.match

✅ pattern matching (s.m.)

❗ casamento de padrões

ver. match

❗ performance

✅ desempenho

❗ query

✅ consulta

❗ queue

✅ fila

❗ receiver

✅ receptor

🔎 recebido, recipiente, destinatário

❗ return (flow control)

✅ retorna

"A função retorna após 10s."

❗ return (value)

✅ devolve

"A função devolve a lista de estudantes."

❗ S-expression

✅ expressão-S

❗ stack

✅ pilha

❗ statement

✅ instrução

✅ status (s.m.)

❗ situação

❗ subject

✅ sujeito

no contexto de pattern matching

✅ thread (s.f.)

❓

"a thread"

❗ tuple

✅ tupla

usar 🇧🇷 exceto menção específica à classe tuple

❗ type hint

✅ dica de tipo

❗ type variable

✅ variável de tipo

❗ type-driven development

✅ desenvolvimento orientado a tipos

❗ weak reference

✅ referência fraca

2. Dicas de formatação

2.1. Uso de maiúsculas em títulos

Somente a primeira letra do título das partes, capítulos e seções deve estar em maiúsculas (além de nomes próprios ;-).

Padrão:
Aventuras aquáticas ao longo do Amazonas

Fora do padrão:
Aventuras Aquáticas ao Longo do Amazonas

2.2. Código dentro do texto corrido

Identificadores de Python devem ser marcados no Asciidoc como `monospace` (delimitado por crases, chr(96), Unicode GRAVE ACCENT).

Nos identificadores __dunder__, é preciso colocar um par de + dentro das crases, assim: `+__dunder__+`. Isso se aplica também a expressões compostas como complex.__float__ que precisa ser escrita como `+complex.__float__+`

Ver literal monospace na documentação do Asciidoctor.

2.3. Reiniciar numeração de exemplos e figuras por capítulo

Logo abaixo do título do capítulo, zere o atribuitos :example-number: e :figure-number:.

Exemplo de cap06.adoc:

[[mutability_and_references]]
== Referências, Mutabilidade, e Memória
:example-number: 0
:figure-number: 0