Guide de composition du code pour les non-programmeurs

Contexte

J'ai rédigé un article scientifique contenant du code et j'ai récemment reçu les épreuves, c'est-à-dire ce que les compositeurs de la revue ont créé à partir de mon manuscrit. Le résultat n'était pas acceptable: le retrait est incohérent; il y a un arrêt complet à la fin de chaque bloc de code; les guillemets ont été détruits, etc. Notez que toutes les erreurs n'étaient pas spécifiques au langage de programmation que j'ai utilisé.

Maintenant, je peux voir pourquoi quelqu'un qui n'a aucune expérience en programmation et sans ressources externes commettrait de telles erreurs, mais à l'époque d'Internet, personne ne devrait être privé de ressources externes. Ainsi, j'ai consulté mon moteur de recherche préféré pour rechercher quelque chose à suggérer et je n'ai rien trouvé. Il existe de nombreux guides pour les programmeurs sur la façon de composer magnifiquement du code dans LaTeX ou similaire, ce qui est tout à fait agréable et approprié, mais cela n'est évidemment pas fait pour le typographe qui doit composer le code de quelqu'un d'autre.

Question

Je recherche une ressource qui:

• explique les bases de la composition du code,
• est destiné aux typographes sans expérience en programmation.

Peut-être que le vrai problème est que le code ne devrait pas vraiment être composé comme les gens comprennent la composition. Ainsi, lorsque vous mettez du code dans un document, il doit y être mis mot à mot , comme dans tous les espaces, les tabulations, les caractères spéciaux ou non et les sauts de ligne intacts.

• Les tabulations doivent être aussi larges que 4 ou 8 espaces (quatre étant le plus courant)
• La police doit être une police à largeur fixe. Et doit être presque universellement .

• Assurez-vous que votre application ne fait aucune substitution!

  Cela signifie pas de ligatures.

  De nombreux programmes (comme Word et InDesign) changent également les guillemets en paires de typographes. Assurez-vous que ces options sont désactivées avant de mettre le code dans votre document.

• Ne laissez pas le code passer automatiquement d'une ligne à l'autre. Ne touchez pas au code, vous n'êtes pas l'expert!

Le code n'est pas un corps de texte, il ne suit aucune convention typographique. Demandez-vous si vous composeriez du texte dans une illustration?

Si vous êtes un expert

Si vous êtes un expert et que vous connaissez la langue en question, alors ce qui suit s'applique.

Remarque : Ne devinez pas et ne déduisez pas, lisez ce qui a été dit. Beaucoup de langues se ressemblent et le code peut être un pseudo-langage qui ressemble à du vrai code. Ensuite vous pouvez:

• Faites un éditeur comme colorier / mettre en gras / mettre en italique les mots-clés si et seulement si votre substitution a la même largeur fixe. Il vaut mieux laisser un éditeur le faire pour vous (les éditeurs comme disons scintilla peuvent exporter le code formaté). N'oubliez pas que l'éditeur doit connaître la langue, peut-être aussi les bibliothèques.

  Notez que si vous faites cela mal, cela cause plus de mal que de bien.

Si vous êtes un expert du domaine. Comme dans connaître la langue et la bibliothèque et comprendre le code en question:

• Ensuite, vous pouvez réaligner le code sur plusieurs lignes s'il ne correspond pas à votre mise en page. Ne faites pas cela à moins que vous ne sachiez vraiment ce que vous faites, vous pourriez finir par faire un tort irréparable.

  Le test décisif est que vous auriez pu écrire le code en question. Sinon, vous ne pouvez pas juger. Demandez à l'auteur.

  Comment y faire face? Les programmeurs comprennent les normes de style de code. Écrivez simplement dans le guide de soumission que vous ne pouvez contenir que X caractères par ligne. Les programmeurs peuvent alors le faire eux-mêmes. Les éditeurs de code disposent fréquemment d'outils pour cela. Encore une autre raison d'utiliser une police à espacement mono.

Mais alors vous saviez tout cela, vous étiez un expert après tout. Mieux vaut laisser l'auteur éditer le code.

Numéros de ligne?

Certains langages de programmation et cas d'utilisation peuvent bénéficier de numéros de ligne. Faites attention ici cependant, car c'est un faux pas dans certaines langues.

Problèmes.

Sachez que, quoi que vous fassiez, vous pourriez être confronté à des obstacles techniques impossibles. Le code ne doit pas vraiment être composé, il doit simplement être du texte non formaté. Cela conduit à des problèmes surprenants.

Par exemple: de nombreuses langues comme Python ne peuvent pas être gérées par de nombreux lecteurs PDF, comme Adobe Acrobat. Si vous collez le code hors du fichier PDF, l'éditeur décide de ne pas inclure l'espace précédent lors du copier-coller. Cela détruit la possibilité de coller du code du PDF vers l'éditeur. Il n'y a vraiment aucun bon moyen de gérer cela!

La réponse peut bien sûr dépendre de nombreux facteurs, mais si nous commençons par un code de texte brut correct et bien formaté , alors on peut plus ou moins généraliser les choses ici.

La «mise en forme» initiale dans le texte source sera: saut de ligne , espace et tabulation . Notez que la nouvelle ligne et le saut de ligne manuel (comme dans le logiciel DTP) ne sont pas la même chose, et vice versa, certaines langues rares peuvent autoriser d'autres caractères de formatage, bien que je n'en ai jamais entendu parler.

Les commentaires ne font pas partie du code exécutable, ils peuvent donc être reformatés sans trop de risques, si l'on sait s'il s'agit vraiment d'un commentaire. La première chose à regarder est donc de savoir comment les commentaires sont balisés.

Il est bon de connaître quelques notions de base sur la mise en forme initiale du texte en clair. Par exemple, pour Python, il y a le guide de style PEP8 . Bien qu'il soit conçu pour Python, ce guide de mise en forme peut être utilisé comme référence pour les principaux langages tels que C / C ++ et Java. L'examen de divers exemples de projets peut aider en cas de doute.

Ainsi, le premier principe serait: ne changez pas le texte source. Je passerais par une liste de contrôle - assurez-vous que:

• Aucun remplacement automatique de personnage ne se produit sur aucune étape.
• Aucune modification du texte n'est effectuée (sauf si vous êtes sûr à 100% qu'elles doivent être effectuées).
• Aucun retour à la ligne n'apparaît.
• Les indentations sont préservées visuellement et sont cohérentes (environ quatre x  largeurs par niveau d'indentation).
• Le niveau de retrait initial (zéro) doit être visible.
• Les styles définis ne détruisent pas la mise en forme de la syntaxe (si la mise en évidence de la syntaxe est utilisée).
• Ayez une sauvegarde de la source en texte brut, afin de pouvoir revérifier le formatage d'origine ou recommencer.
• Les numéros de ligne, s'ils sont présents, doivent être intacts, surtout s'ils sont référencés dans les explications.

En fait, si la source d'origine est correctement formatée, il ne devrait y avoir aucun retour à la ligne. Si des lignes enveloppées apparaissent toujours et sont inévitables, un retrait à un niveau est la solution la plus courante (voir PEP lié ci-dessus). Si un saut de ligne est nécessaire - mieux consulter le guide de style ou l'auteur.

Certains caractères «espaces blancs» mineurs peuvent nécessiter un remplacement. Puisque la source peut inclure des caractères de tabulation, cela signifie bien sûr que le typographe doit s'assurer que tous les tabulations au début de chaque ligne sont cohérentes, c'est-à-dire que les indentations imbriquées sont préservées visuellement et que chaque niveau d'indentation suivant est de la même largeur (environ quatre x  largeurs pour un niveau d'indentation).

Idéalement, les indentations qui ont été faites avec des caractères d'espace ou des espaces et des tabulations mixtes devraient être remplacées par une tabulation (ou avec ce que le logiciel DTP peut faire mieux pour les indentations imbriquées), donc, si nécessaire, l'ajustement des indentations peut être plus facile.
Bien sûr, on peut laisser des espaces, mais il peut être plus difficile de gérer leur largeur lors du changement de police et plus difficile d'aligner les indentations de la ligne intérieure comme dans les colonnes du tableau.

Police + espaces espacés

Notez que si la source est formatée avec des espaces intentionnellement et était destinée à être lue uniquement en police à espacement fixe (par exemple, les diagrammes ASCII ou l'art ASCII), il faut conserver les espaces totalement inchangés , mais cette décision doit être prise depuis le début. La police "Courier New" est la plus courante dans ce cas. Toujours si ce n'est pas vraiment nécessaire, je déconseille les espaces fixes, car de moins en moins de nouvelles personnes choisissent aujourd'hui l'espace fixe pour le codage, et en cas de relecture, les polices proportionnelles offriront une meilleure expérience de lecture.

En général, les polices condensées (par exemple Arial étroit) ou plus petites peuvent mieux fonctionner: elles mettent davantage l'accent contrairement au corps du texte, elles rendent le code plus compact et donc moins probable que des retours à la ligne indésirables apparaissent.

Je pense qu'ici, on peut tracer une ligne, et si ce qui précède est fait, il y a alors une probabilité de 99% que tout se passe bien, au moins pour un bloc de code à une seule police sans couleurs.

Outils et formatage avancé

De plus, l'apparence peut être considérablement améliorée en utilisant la coloration syntaxique.

• impression en couleur ou affichage à l'écran: dans une mise en page en couleur, toutes les fonctionnalités de la mise en surbrillance peuvent être utilisées, c'est donc le meilleur des cas, mais l'impression peut entraîner des changements de couleur.

• niveaux de gris ou impression noir et blanc: ici, bien sûr, on peut utiliser des caractères gras (par exemple, des mots clés) ou en italique (par exemple des commentaires), mais notez que les couleurs seront converties en gris avec toutes les conséquences. Par exemple, les commentaires grisés peuvent être superbes sur un écran, mais peuvent devenir trop pâles sur le papier.

La question la plus importante est de savoir si le créateur de mise en page dispose d'outils qui peuvent représenter le code sous une forme lisible. Heureusement, il existe de nombreux outils gratuits pour l'édition de code, les plus importants (pour Windows) sont: Notepad ++, VSCode, Visual Studio . Mais soyez conscient des possibles conversions automatiques implicites des tabulations en espaces.

Dans Notepad ++, il existe une option pour exporter le code au format RTF , ce qui préservera tout le formatage et la coloration syntaxique de la source.

Si la mise en page ne nécessite pas de modification du flux de texte dans la présentation du code, on peut directement utiliser des images (captures d'écran) - elle n'est pas aussi flexible que le texte, mais conservera un formatage et une numérotation des lignes à 100%, et peut gagner beaucoup de temps. Par exemple, les numéros de ligne peuvent être difficiles à conserver sous forme de texte. L'exportation au format PDF est également une bonne alternative - mais tous les logiciels DTP ne peuvent pas intégrer de fichiers PDF et certains formats peuvent être perdus lors de l'impression au format PDF.

Par exemple, ma configuration pour le code Python dans Notepad ++ ressemble à ceci:

Ceci est juste pour illustrer, que l'on peut utiliser directement des captures d'écran et qui peut en fait être la méthode la plus simple. Il existe divers outils qui peuvent aider à la capture d'écran - on peut avoir besoin de «recoudre» les écrans pour des images de plus haute résolution.

Le jeu de couleurs est bien sûr individuel, défini dans le configurateur de style de l'éditeur, qui connaît déjà la langue prise en charge, ce qui rend difficile la fausse mise en forme même si l'on ne connaît pas la syntaxe. Ici, les règles générales de typographie devraient fonctionner: pas trop de couleurs, polices cohérentes, indentations, interligne confortable.

Des outils / plugins supplémentaires pour les définitions de langage personnalisé sont également courants, mais ceux-ci nécessitent une connaissance de la syntaxe.

En HTML, il existe un jeu de balises <code> ... </code> qui indique au lecteur / interprète de traiter le contenu de façon absolument littérale. aussi, <pre> ... </pre> fait à peu près la même chose. En tant que personne qui a souvent dû composer des formules, des équations et du code pour la publication, je préconise également l'utilisation d'IMAGES pour ce faire ... créer un .gif ou .jpg ou .png de l'élément problématique.

Un autre facteur est que le code est traditionnellement rendu en monospace Courier ou en une autre police à espacement fixe, car il sémaphorise ou télégraphie au lecteur qu'il ne s'agit pas d'un corps de texte. Je souscris à ce choix de style, je pense que cela a beaucoup de sens.

Dans la plupart des systèmes de composition "hérités", les équations mathématiques d'une complexité raisonnablement élevée prenaient un temps atroce ... et étaient lourdes d'erreurs.