Guide de composition du code pour les non-programmeurs

13

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.
Wrzlprmft
la source
La difficulté avec cela est que cela dépend du langage et des conventions utilisés, donc la question est assez large, même si les réponses ne font que lier une ressource
Zach Saucier
2
@Scott Eh bien, en ce qui concerne les guillemets, les espaces, les caractères - en effet, on peut assez bien généraliser: ils doivent être préservés.
Mikhail V
1
@MikhailV Je pense simplement que de nombreux langages de code ont plus en commun avec les langues étrangères que de simples directives. Bien sûr, vous pouvez déterminer approximativement où les espaces et les sauts de ligne doivent être placés, mais pour être précis, vous devez vraiment comprendre la langue que vous relisez. Oui, vous pouvez dire aux éditeurs / correcteurs de laisser «tel quel», ce qui ne veut pas dire que ce sera finalement correct.
Scott
1
@Wrzlprmft Chose amusante, on ne peut pas copier coller python sous forme PDF sans perdre tous les espaces précédents dans acrobat ou acrobat reader. Il les supprime "intelligemment". De même, si vous collez du code dans de nombreux éditeurs WYSIWYG comme word ou INdesign, ils remplaceront les guillemets par des citations de typographes (sauf si vous désactivez une telle fonctionnalité), mais pour le code qui est effectivement MAUVAIS. De plus, dans idesign, vous ne pouvez pas vraiment composer du code correctement sans introduire un caractère différent pour le saut de ligne, ce qui pourrait bien devenir une mauvaise chose si vous recopiez le code.
joojaa
1
@ usr2564301: Tout d'abord, cette question est maintenant trouvée par certains moteurs de recherche et il est donc plus probable que tout typographe ayant les mêmes problèmes que le mien puisse trouver une réponse potentielle (et s'ils ne le font pas, je pourrais être correctement suffisant) à propos de ça). Deuxièmement, oui, j'inclurais un lien dans la réponse à mes preuves, car cela peut empêcher les erreurs non encore commises lors de la deuxième série de preuves. Cela ne fait pas de mal non plus d'avoir une référence si le typographe est têtu. Enfin, il s'agit d'un journal / éditeur qui a rarement à traiter avec du code, il est donc quelque peu différent des scénarios que vous décrivez.
Wrzlprmft

Réponses:

7

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!

joojaa
la source
@ usr2564301 ah oui si vrai
joojaa
1
@ usr2564301 Terminé, de toute façon je pense qu'un choix de police lisible est quelque chose qu'un typographe devrait comprendre. Quoi qu'il en soit, celui qui distingue également un minuscule i sans point (oui, nous avons débogué une seule partie du code pendant un mois parce que nous ne savions pas qu'un `` i '' minuscule est différent d'un `` I '' majuscule dans une langue turque) forme un 1 aussi
joojaa
«Ne laissez pas le code passer d'une ligne à l'autre» est un bon conseil en théorie. Mais si vous composez pour un format d'impression 6x9 standard et que vous avez une ligne de code avec 600 caractères, vous aurez du mal à en tenir compte.
Janus Bahs Jacquet le
1
@JanusBahsJacquet Code est généralement écrit à moins de 80 caractères par ligne. Donc, si vous obtenez quelque chose comme ça, alors peut-être que vos directives de soumission sont nulles. Les programmeurs connaissent les directives de soumission, après tout c'est ce que sont les bases de code. La chose est qu'en brisant les lignes, vous pouvez finir par changer la signification du code.
joojaa
1
@JanusBahsJacquet C'est pourquoi vous demandez à l'auteur, vous mettez à jour les directives afin que vous n'ayez pas besoin de le faire trop souvent. bien dans les deux cas si le code ne peut pas être divisé en longues lignes, le compositeur ne peut rien faire non plus. Au fait, que ferait un typographe pour une image trop large qui ne peut pas être redimensionnée ou recadrée? Quoi qu'il en soit, je prédis que les soumissions de code seront plus courantes à l'avenir
joojaa
4

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:
entrez la description de l'image ici

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.

Mikhail V
la source
C'est une réponse merveilleuse et mûrement réfléchie. Mais les captures d'écran peuvent être sous-optimales si vous prévoyez de l'imprimer, en raison de la résolution. Quelque chose à garder à l'esprit.
Jeremy Carlson
1
@JeremyCarlson dans Np ++, la taille de la police / l'espacement des lignes peuvent également être ajustés - donc en théorie, il n'y a pas de limite pour la résolution de capture d'écran, mais il sera plus difficile à créer, en particulier sur un petit écran. Il peut même y avoir une astuce pour utiliser l'affichage virtuel et définir une très grande taille de fenêtre
Mikhail V
parce que de moins en moins de nouvelles personnes choisissent le monospace pour le codage aujourd'hui - C'est possible, mais le monospace est toujours utilisé par la grande majorité. Vous ne pouvez pas simplement traduire des conventions de composition normales en code. Par exemple, les signes de ponctuation sont plus importants que dans les textes normaux (la plupart des arguments de ma réponse se traduisent par ceci). Une police de code non monospace diffère considérablement de celle d'un texte normal. De plus, vous souhaitez souvent que certaines structures similaires soient alignées horizontalement, par exemple a[i][j] = 1a[m][n] = 2.
Wrzlprmft
@Wrzlprmft merci pour les modifications. Et oui, il n'y a pas tant de bonnes polices optimisées pour le code et les mathématiques (Verdana est ok). En effet, Times a une petite période et deux points et d'autres problèmes, mais je l'utilise tout le temps - `` les avantages l'emportent sur les coûts ''
Mikhail V
-5

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.

dwoz
la source
bien sûr, les images ne sont pas coupables et collables!
dwoz
3
Je ne comprends pas du tout comment cela répond à la question posée
Zach Saucier