Guia para digitar código de código para não programadores

fundo

Eu escrevi um artigo científico contendo código e recebi recentemente as provas, ou seja, o que os tipógrafos da revista criaram a partir do meu manuscrito. O resultado não foi aceitável: O recuo é inconsistente; há um ponto final no final de cada bloco de código; as aspas foram destruídas, etc. Observe que todos os erros não eram específicos da linguagem de programação que eu usei.

Agora, posso entender por que alguém que não tem experiência em programação nem recursos externos cometeria tais erros, mas em tempos da Internet ninguém deveria ficar sem recursos externos. Assim, consultei meu mecanismo de pesquisa favorito para procurar algo para sugerir e encontrar ... nada. Existem muitos guias para programadores sobre como digitar lindamente um código no LaTeX ou similar, o que é legal e adequado, mas isso obviamente não foi feito para o tipógrafo que precisa digitar o código de outra pessoa.

Questão

Estou procurando um recurso que:

• explica os conceitos básicos de código de digitação,
• é direcionado a tipógrafos sem experiência em programação.

Talvez o ponto real seja que o código não deva realmente ser digitado da maneira como as pessoas entendem a digitação. Portanto, ao colocar o código em um documento, ele deve ser colocado literalmente , como em todos os espaços, guias, caracteres especiais ou não especiais e quebras de linha intactas.

• As guias devem ter até 4 ou 8 espaços (quatro sendo os mais comuns)
• A fonte deve ser uma fonte de largura fixa. E quase universalmente tem que ser.

• Verifique se o seu aplicativo não faz substituições!

  Isso significa que não há ligaduras.

  Muitos aplicativos (como Word e InDesign) também alteram aspas diretas para pares de tipógrafos. Verifique se essas opções estão desabilitadas antes de inserir o código no seu documento.

• Não permita que o código flua automaticamente de uma linha para outra. Não toque no código, você não é o especialista!

Código não é texto do corpo, não segue nenhuma convenção tipográfica. Pergunte a si mesmo que você digitaria texto em uma ilustração?

Se você é um especialista

Se você é um especialista e conhece o idioma em questão, aplica-se o seguinte.

Nota : Não adivinhe ou deduza, leia o que foi dito. Muitos idiomas têm a mesma aparência e o código pode ser uma pseudo linguagem que se parece com um código real. Então você pode:

• Editor como coloração / negrito / itálico de palavras-chave se e somente se sua substituição tiver a mesma largura fixa. É melhor deixar um editor fazer isso por você (editores como o scintilla podem exportar o código formatado). Lembre-se de que o editor precisa conhecer o idioma, talvez também as bibliotecas.

  Observe que se você fizer isso errado, causa mais mal do que bem.

Se você é um especialista em domínio. Como conhecer o idioma e a biblioteca e entender o código em questão:

• Em seguida, você pode realinhar o código em várias linhas, se ele não se ajustar ao seu layout. Não faça isso a menos que você realmente saiba o que está fazendo, pois poderá acabar causando danos irreparáveis.

  O teste decisivo é: você poderia ter escrito o código em questão. Se não, então você não pode julgar. Pergunte ao autor.

  Como lidar com isso? Os programadores entendem os padrões de estilo de código. Basta escrever na diretriz de envio que você pode ajustar apenas X caracteres por linha. Os programadores podem fazer isso sozinhos. Os editores de código freqüentemente têm ferramentas para isso. Outro motivo para usar uma fonte mono espaçada.

Mas então você sabia tudo isso, afinal era um especialista. Melhor deixar o autor editar o código.

Números de linha?

Algumas linguagens de programação e casos de uso podem se beneficiar dos números de linha. Tenha cuidado aqui, porém, uma vez que este é um artigo falso em alguns idiomas.

Problemas.

Esteja ciente de que não importa o que você faça, você pode de fato enfrentar obstáculos técnicos impossíveis. O código não deve realmente ser digitado, deve ser apenas um texto não formatado. Isso leva a problemas surpreendentes.

Por exemplo: idiomas como Python não podem ser manipulados por muitos visualizadores de PDF, como o Adobe Acrobat. Se você colar o código do arquivo PDF, o editor decidirá não incluir o espaço anterior ao colar a cópia. Isso destrói a capacidade de colar o código do PDF no editor. Realmente não há uma boa maneira de lidar com isso!

A resposta, é claro, pode depender de muitos fatores, mas se começarmos com um código de texto simples formatado, correto e correto, é possível generalizar mais ou menos as coisas aqui.

A 'formatação' inicial no texto de origem será: nova linha , espaço e caracteres de tabulação . Observe que a nova linha e a quebra manual de linha (como no software DTP) não são a mesma coisa, e vice-versa, alguns idiomas raros podem permitir outros caracteres de formatação, embora eu nunca tenha ouvido falar disso.

Os comentários não são parte executável do código; portanto, eles podem ser reformatados sem muito risco, se alguém souber se é realmente um comentário. Portanto, a primeira coisa a observar é como os comentários são marcados.

É bom saber alguns conceitos básicos sobre a formatação inicial de texto sem formatação. Por exemplo, para Python, existe o guia de estilo PEP8 . Embora tenha sido feito para Python, este guia de formatação pode ser usado como referência para as principais linguagens, como C / C ++ e Java. Examinar vários exemplos de projetos pode ajudar em caso de dúvida.

Assim, o primeiro princípio seria: não altere o texto fonte. Gostaria de passar por uma lista de verificação - verifique se:

• Não há substituição automática de caractere em nenhum estágio.
• Nenhuma edição no texto é feita (a menos que você tenha 100% de certeza de que deve ser feito).
• Nenhuma quebra de linha aparece.
• Os recuos são preservados visualmente e são consistentes (cerca de quatro x  larguras por nível de recuo).
• O nível de recuo inicial (zero) deve estar visível.
• Os estilos definidos não destroem a formatação da sintaxe (se o realce da sintaxe for usado).
• Faça um backup da fonte em texto sem formatação, para poder verificar novamente a formatação original ou iniciar novamente.
• Os números de linha, se presentes, devem estar intactos, especialmente se forem mencionados nas explicações.

Na verdade, se a fonte original estiver formatada corretamente, não haverá quebra de linha. Se as linhas quebradas ainda aparecerem e forem inevitáveis, um recuo suspenso de um nível é a solução mais comum (consulte o PEP vinculado acima). Se a quebra de linha for necessária - consulte melhor o guia de estilo ou o autor.

Ainda alguns caracteres menores de 'espaço em branco' podem exigir substituição. Como a fonte pode incluir caracteres de tabulação, é claro que o tipógrafo deve garantir que todas as guias no início de cada linha sejam consistentes, ou seja, os recuos aninhados são preservados visualmente e todos os próximos níveis de recuo têm a mesma largura (cerca de quatro x  larguras por um nível de recuo).

Idealmente, as indentações feitas com caracteres de espaço ou espaços e tabulações misturadas devem ser substituídas por tabulação (ou pelo que o software DTP pode fazer melhor para indentações aninhadas); portanto, se necessário, o ajuste das indentações pode ser mais fácil.
Obviamente, pode-se deixar espaços, mas pode ser mais difícil gerenciar sua largura ao alterar a fonte e mais difícil alinhar os recuos da linha interna, como nas colunas da tabela.

Fonte monoespaçada + espaços

Observe que, se a fonte for formatada com espaços intencionalmente e tiver a intenção de ser lida apenas em fonte monoespaçada, (por exemplo, diagramas ASCII ou arte ASCII), deve-se preservar os espaços totalmente inalterados , mas essa decisão deve ser tomada desde o início. A fonte "Courier New" é mais comum neste caso. Ainda assim, se não for realmente necessário, aconselho contra o monoespaçado, porque cada vez menos pessoas escolhem o monoespaço para a codificação hoje e, no caso de revisão, as fontes proporcionais proporcionam uma melhor experiência de leitura.

Em geral, as fontes condensadas (por exemplo, Arial narrow) ou menores podem funcionar melhor: dá mais ênfase ao contraste com o texto do corpo, tornam o código mais compacto e, portanto, menos provável que apareça linhas indesejadas.

Acho que aqui se pode traçar uma linha, e se o acima for feito, há 99% de probabilidade de que tudo esteja bem, pelo menos para um bloco de código simples de fonte única sem cores.

Ferramentas e formatação avançada

Além disso, a aparência pode ser significativamente aprimorada usando o realce da sintaxe.

• impressão em cores ou visualização em tela: em um layout colorido, todos os recursos de destaque podem ser usados, por isso é o melhor cenário, mas a impressão pode causar algumas alterações de cores.

• escala de cinza ou preto e branco: aqui é claro que se pode usar negrito (por exemplo, palavras-chave) ou itálico (por exemplo, comentários), mas observe que as cores serão convertidas em cinza com todas as consequências. Por exemplo, os comentários acinzentados podem parecer ótimos em uma tela, mas podem ficar muito claros no papel.

A questão mais importante é se o criador do layout possui ferramentas que podem representar o código de forma legível. Felizmente, existem muitas ferramentas gratuitas para edição de código, as mais importantes (para Windows) são: Notepad ++, VSCode, Visual Studio . Mas esteja ciente de possíveis conversões automáticas implícitas de guias em espaços.

No Notepad ++, há uma opção para exportar o código como RTF , o que preservará toda formatação e destaque de sintaxe da fonte.

Se o layout não exigir alteração do fluxo de texto na apresentação do código, é possível usar diretamente imagens (capturas de tela) - não é tão flexível quanto o texto, mas preservará a formatação e a numeração de linha 100%, além de economizar muito tempo. Por exemplo, números de linha podem ser difíceis de preservar em forma de texto. Também exportar para PDF é uma boa alternativa - mas nem todo software DTP pode incorporar PDFs e algumas formatações podem ser perdidas ao imprimir em PDF.

Por exemplo, minha configuração do código Python no Notepad ++ é assim:

Isso é apenas para ilustrar que é possível usar diretamente capturas de tela e que pode ser o método mais fácil. Existem várias ferramentas que podem ajudar na captura de tela - pode ser necessário 'unir' as telas para obter imagens de alta resolução.

É claro que o esquema de cores é individual, definido no configurador de estilos do editor, que já conhece o idioma suportado, dificultando a formatação falsa, mesmo que não se conheça a sintaxe. Aqui, as regras gerais de tipografia devem funcionar: poucas cores, fontes consistentes, recuos, espaçamento confortável entre linhas.

Ferramentas / plug-ins adicionais para definições de linguagem personalizadas também são comuns, mas requerem conhecimento de sintaxe.

No HTML, existe um conjunto de tags <code> ... </code> que informa ao leitor / intérprete para tratar o conteúdo absolutamente literalmente. Além disso, <pre> ... </pre> faz o mesmo. Como alguém que muitas vezes precisou digitar fórmulas, equações e códigos para publicação, também defendo o uso de IMAGES para fazer isso ... crie um .gif ou .jpg ou .png do item problemático.

Outro fator é que o código é tradicionalmente renderizado no Courier monospace, ou em outra fonte monospace, porque semáfora ou telégrafo para o leitor que não é um texto corporal. Eu assino essa escolha de estilo, acho que faz muito sentido.

Na maioria dos sistemas de composição "legados", as equações matemáticas de complexidade razoavelmente alta consomem muito tempo ... e estão repletas de erros.