Tempo estimado: 20 minutos
Engenheiros de software geralmente tentam minimizar o número de linhas de código em uma implementação pelos seguintes motivos:
De fato, as mesmas regras se aplicam à redação técnica:
Implementar uma documentação mais curta leva tempo, mas vale a pena. Frases curtas se comunicam melhor do que frases longas, e frases curtas geralmente são mais fáceis de entender do que frases longas.
Concentre cada frase em uma única ideia, pensamento ou conceito. Assim como as instruções em um programa executam uma única tarefa, as sentenças devem executar uma única ideia. Por exemplo, a frase muito longa a seguir contém vários pensamentos:
O final da década de 1950 foi uma era chave para as linguagens de programação, porque a IBM introduziu o Fortran em 1957 e John McCarthy introduziu o Lisp no ano seguinte, o que deu aos programadores uma maneira iterativa de resolver problemas e uma maneira recursiva.
Quebrar a frase longa em uma sucessão de frases de ideia única produz o seguinte resultado:
O final da década de 1950 foi uma era chave para as linguagens de programação. A IBM introduziu o Fortran em 1957. John McCarthy inventou o Lisp no ano seguinte. Consequentemente, no final da década de 1950, os programadores podiam resolver problemas de forma iterativa ou recursiva.
Converta a seguinte frase excessivamente longa em uma série de frases mais curtas. Não revise muito; apenas termine com algumas frases em vez de apenas uma.
No bash, use as instruções if, then e fi para implementar um bloco de ramificação condicional simples no qual a instrução if avalia uma expressão, a instrução then introduz um bloco de instruções a serem executadas quando a expressão if for verdadeira e a instrução fi marca o final do bloco de ramificação condicional.
No bash, use uma instrução if, then e fi para implementar um bloco de ramificação condicional simples. A instrução if avalia uma expressão. A instrução then introduz um bloco de instruções a serem executadas quando a expressão if for verdadeira. A instrução fi marca o fim do bloco de ramificação condicional. (O parágrafo resultante continua não sendo claro, mas ainda é muito mais fácil de ler do que a frase original.)
Dentro de muitas frases técnicas longas há uma lista querendo se libertar. Por exemplo, considere a seguinte frase:
Para alterar o fluxo normal de um loop, você pode usar uma instrução
break(que o pula para fora do loop atual) ou uma instruçãocontinue(que pula o restante da iteração atual do loop atual).
Quando você vir a conjunção ou em uma frase longa, considere refatorar essa frase em uma lista com marcadores. Quando você vir uma lista de itens ou tarefas incorporada em uma frase longa, considere refatorar essa frase em uma lista com marcadores ou numerada. Por exemplo, o exemplo anterior contém a conjunção ou, então vamos converter essa frase longa para a seguinte lista com marcadores:
Para alterar o fluxo normal de um loop, chame uma das seguintes instruções:
break, que faz você sair do loop atual.continue, que pula o restante da iteração atual do loop atual.
Refatore as frases a seguir em algo mais curto e claro. Certifique-se de que sua resposta contém uma lista:
Foo no arquivo /etc/Frambus e, em seguida, execute-o falando a palavra mágica duas vezes.Frase 1
Siga os seguintes passos para começar a usar o aplicativo Frambus:
Foo no arquivo /etc/Frambus.Frase 2
Os seguintes dois cientistas da computação do Bell Labs inventaram shells populares:
O KornShell é um superconjunto compatível com versões anteriores do Bourne Shell, contendo muitas melhorias em relação ao shell mais antigo.
Muitas frases contêm palavras que apenas incham o texto — lixo textual que consome espaço sem ajudar o leitor. Por exemplo, veja se você consegue identificar as palavras desnecessárias na seguinte frase:
Um valor de entrada maior que 100 causa o acionamento do log.
Substituir causa o acionamento do com o verbo mais curto aciona resulta numa frase mais curta:
Um valor de entrada maior que 100 aciona o log.
Com a prática, você identificará as palavras extras e ficará muito feliz em removê-las ou reduzi-las. Por exemplo, considere a seguinte frase:
Este documento de design fornece uma descrição detalhada do Projeto Frambus.
A frase fornece uma descrição detalhada de se reduz ao verbo descreve (ou o verbo detalha), de modo que a sentença resultante pode se tornar:
Este documento de design descreve o Projeto Frambus.
A tabela a seguir sugere substituições para algumas frases que normalmente podem ser reduzidas:
| Palavras demais | Conciso |
|---|---|
| no momento atual | agora |
| determinar a localização de | encontrar |
| é capaz de | pode |
Encurte as seguintes frases sem alterar o seu significado:
Aqui estão algumas soluções possíveis:
Uma sentença é um fragmento lógico independente de uma oração, a qual contém um ator e uma ação. Cada sentença contém o seguinte:
As orações subordinadas modificam a ideia da oração principal. Como o nome indica, as orações subordinadas são menos importantes que a oração principal. Por exemplo, considere a seguinte frase:
Python é uma linguagem de programação interpretada, que foi inventada em 1991.
- cláusula principal: Python é uma linguagem de programação interpretada
- oração subordinada: que foi inventada em 1991
Geralmente você pode identificar orações subordinadas pelas palavras que as introduzem. A lista a seguir (longe de estar completa) mostra palavras comuns que introduzem orações subordinadas:
Algumas orações subordinadas começam com uma vírgula e outras não. A oração subordinada destacada na frase a seguir, por exemplo, começa com a palavra porque e não contém vírgula:
Prefiro codificar em C++ porque gosto de tipagem de dados forte.
Ao editar um texto, avalie as orações subordinadas. Siga o conceito de uma frase = uma ideia em mente. As orações subordinadas de uma frase ampliam a ideia principal ou se ramificam em uma nova ideia separada? Se for a segunda opção, considere dividir a(s) oração(ões) subordinada(s) ofensora(s) em frases separadas.
Determine quais das frases contêm orações subordinadas que devem ser ramificadas em frases separadas. (Não reescreva as frases, apenas identifique as frases que devem ser reescritas.)
As orações subordinadas estão sombreadas a seguir:
Que e o(a) qual quase sempre iniciam orações subordinadas. Qual é a diferença entre eles? Bem, no Brasil, ambos são praticamente intercambiáveis.
No entanto, procure reservar o(a) qual para orações subordinadas não essenciais e usar que para uma oração subordinada essencial sem a qual a sentença não pode viver. Por exemplo, a mensagem principal na frase a seguir é que Python é uma linguagem interpretada; a frase pode sobreviver sem Guido van Rossum ser o inventor:
Python é uma linguagem interpretada, a qual Guido van Rossum inventou.
Por outro lado, a seguinte frase precisa do trecho que não envolvem álgebra linear:
Fortran é perfeito para cálculos matemáticos que não envolvem álgebra linear.
Se você ler uma frase em voz alta e perceber uma pausa antes da oração subordinada, use o(a) qual. Se você não perceber uma pausa, use que. Volte e leia as duas frases de exemplo anteriores. Você ouve a pausa na primeira frase?
Coloque uma vírgula antes de o(a) qual; não coloque uma vírgula antes de que.
O conteúdo desta página é uma tradução livre e adaptada. O material original está disponível em inglês no Google Developers sob a licença Creative Commons (CC BY 4.0).