Que fait Anglais Simple ?
Dites l'essentiel en aussi peu de mots ordinaires que possible, et arrêtez-vous. Le lecteur ouvre le code pour les détails.
Soyez concis
- Commencez par l'essentiel : ce que fait la chose, et pourquoi quand ce n'est pas évident.
- Omettez ce que le code ou le diff montre déjà : les fichiers modifiés, l'ordre des étapes, les cas particuliers que le code gère.
- Utilisez l'expression concise du métier : « supprimer les icônes inutilisées », pas « supprimer les icônes que rien n'utilise ».
- Dites un fait une fois.
- Coupez les mots, pas les faits. Gardez chaque étape dont le lecteur a besoin pour voir le problème, et énoncez la conséquence : « cette date peut différer du jour où CI fabrique la release », pas « l'en-tête est écrit avant le jour de la release ».
Restez clair
Concis n'est pas cryptique.
- Écrivez une idée par phrase, avec un sujet et un verbe. Pas de point-virgule, d'énigme ou de slogan, comme « pas de release, pas de type ».
- Placez le sujet en premier et nommez qui agit : « C++ calcule X », pas « X est calculé en C++ ».
- Utilisez des temps simples, et le présent pour ce qui est toujours vrai : « QML ne réévalue jamais les liaisons dessus », pas « n'a jamais été réévalué ».
- Écrivez une condition comme
Si X, Y. - Répétez le nom au lieu de « il », « elle » ou « ceux-ci » quand le nom est une proposition éloignée ou quand plusieurs noms pourraient correspondre.
- Gardez les propositions avec « lequel » ou « dont » courtes. Si la proposition a un sujet long, écrivez une phrase séparée : « Les paquets Qt de Debian et Ubuntu ne l'ont pas », pas « , que les paquets Qt de Debian et d'Ubuntu omettent ».
- Dites une négation simplement : « ignorer les valeurs en dehors de l'intervalle », pas « ne prendre aucune valeur au-delà de l'intervalle ». Ne niez pas par l'objet : « la modification n'a pas émis updated() », pas « la modification n'a émis aucun updated() ». Écrivez « ni » seulement après « ne ».
Sonnez natif
Le texte doit se lire comme quelque chose qu'un développeur anglophone a écrit. Si une phrase se lit comme une traduction, réécrivez-la, même si la réécriture est plus longue d'un mot.
- Utilisez des noms composés, pas des chaînes de « de » : « paramètres de l'application », « la boîte de dialogue du fichier CSV », « les paquets Qt de Debian et Ubuntu ». Utilisez un possessif seulement quand aucun composé ne fonctionne, comme « la densité de la feuille », et jamais deux à la suite. Autorisez au maximum un « de » par expression.
- Utilisez le verbe usuel du métier : « afficher », « signaler », « corriger », « prendre en charge », « gérer », « vérifier ». Ne faites pas du code une personne qui dit, répond ou porte. Réservez « posséder » pour la propriété au sens C++.
- Utilisez un mot par concept : choisissez « vérifier » ou « contrôler », « paramètres » ou « options », et gardez-le.
- Ne répétez pas l'article dans une liste : « le cadre et le bouton de suppression ».
- Écrivez « doit » pour une obligation et « peut » pour une possibilité. Évitez « devrait », « peut-être » et « pourrait ».
- Écrivez « par exemple », pas « e.g. ». Utilisez l'orthographe américaine.
- Supprimez ces mots : « tirer parti » et « utiliser » (écrivez « utiliser »), « afin de » (écrivez « pour »), « avant de » (écrivez « avant »), « garantir », « simplement », « juste », « facilement », « en toute transparence », « robuste », « puissant », « complet », « fonctionnalité », « il est à noter que », « avec ce changement », « est conçu pour », « vous permet de » (nommez la chose et son verbe), « sous le capot », « prêt à l'emploi ».
Avant et après, tirés de véritables sujets de commit :
| Avant | Après |
|---|---|
| garder les paramètres de l'app hors des documents | ne pas enregistrer les paramètres de l'application dans les documents |
| Graph : dire au lecteur quand un export échoue | Graph : signaler les erreurs d'export |
| ajouter CardButton, le bouton d'icône de la ligne supérieure d'un objet | ajouter CardButton, le bouton d'icône sur la ligne supérieure d'un objet |
| Sampler : ne prendre aucune valeur d'un objet discret au-delà de son intervalle | Sampler : ignorer les valeurs d'objet discret en dehors de l'intervalle |
| arrêter une release complète dont les notes portent un autre jour | vérifier la date dans les notes de release avant une release complète |
| compiler sur Ubuntu 26.04, avec ses paquets de Qt | compiler sur Ubuntu 26.04, avec ses paquets Qt |
Par type de texte
Message de commit
- Écrivez le sujet comme un impératif court qui a du sens sans le diff : « limiter les valeurs du document aux limites du panneau de paramètres », pas « garder les nombres d'un document dans l'intervalle du panneau ».
- Un commit fait une chose. Si le corps a besoin d'un deuxième sujet, scindez le commit.
- Commencez le corps par ce que le code fait maintenant, puis un bref pourquoi.
- Marquez un fait au-delà du sujet par « aussi » : « Les deux lectures ignorent aussi les clés inconnues, car les versions plus récentes peuvent en ajouter. »
- Supprimez le contexte que le lecteur connaît. Ne racontez pas le diff et ne défendez pas le changement.
Commentaire de code
- N'en écrivez aucun par défaut. Écrivez-en un pour une raison que le code ne montre pas, un invariant caché, ou un contournement.
- Dites ce que le code fait, ce qui en découle, et pourquoi, une courte phrase chacun. Sautez une partie que le code montre déjà.
- Nommez l'API et n'utilisez pas de métaphores. L'impératif convient : « ignorer les écritures identiques : elles mettent quand même à jour le mtime ».
- Écrivez le commentaire que vous donneriez à un collègue qui demande « pourquoi est-ce ici ? ». Nommez l'effet concret, comme « xmin reste à gauche », pas un résumé comme « les limites sont où elles sont ».
Exemples :
- Avant :
// une liste verticale garde sa largeur secrète, donc le style peint une poignée errante - Après :
// une ListView verticale laisse contentWidth à -1, ce que le style rend comme une poignée réduite - Avant :
# le glib et le libsystemd du runner ont besoin de son nouveau glibc, donc l'AppImage utilise le glib et le libdbus de l'hôte. linuxdeploy copie toujours les bibliothèques dont eux seuls ont besoin, donc la liste les nomme aussi - Après :
# ne pas inclure glib, libdbus et leurs dépendances. L'AppImage charge alors les versions de l'hôte. Les versions Ubuntu 26.04 ont besoin de glibc 2.43, ce qui manque aux anciennes distributions.
Documentation
- Décrivez ce que le code fait aujourd'hui. Nommez la chose et à quoi elle sert, et pointez vers le fichier avec les détails.
- Mettez trois éléments parallèles ou plus dans une liste à puces.
- Mettez les noms de style, de module et d'identifiant entre backticks :
FluentWinUI3. - Marquez un fait concernant un logiciel tiers qui peut changer par « actuellement » ou la version : « Les paquets Qt de Debian et Ubuntu ne l'ont actuellement pas. »
Message d'erreur : ce qui s'est passé, la cause si elle est connue, et quoi faire. Pas d'excuse.
Infobulle : ce que le widget définit.
Instructions pour un agent : une règle par phrase, la condition en premier.
Laissez tranquille
Le code, les identifiants, les commandes, les chemins, les messages entre guillemets, les noms de produits, et les noms de boutons, onglets, champs et entrées de menu.
Avant de livrer
Lisez le texte une fois comme son lecteur. Supprimez chaque phrase qui n'aide pas ce lecteur. Vérifiez que chaque phrase restante se lit correctement du premier coup et ressemble à de l'anglais courant.
Si vous avez expliqué la même chose en chat, comparez les deux. Si la version du chat est plus claire, utilisez-la.