Commencer une phrase avec un nom de fonction? [fermé]

42

Parfois, en tapant quelque chose qui concerne un langage de programmation sensible à la casse, je commence une phrase avec un nom de fonction. Maintenant, les règles de l'anglais stipulent que le premier mot d'une phrase doit être mis en majuscule; le nom de la fonction est minuscule, cependant. Si vous vous demandez qu'est-ce que je pourrais dire qui ferait que le premier mot serait un nom de fonction, prenons cet exemple:

Votre implémentation de fread est cassée. fread doit renvoyer le nombre d'octets lus.

Je comprends que je pourrais changer le deuxième cas de fread en It, mais je veux connaître le meilleur moyen de gérer cela autrement que de simplement réécrire la phrase. Devrais-je mettre en majuscule le nom de la fonction? La seule façon pour laquelle je voudrais entendre «réécrire la phrase» est de répondre si le fait de commencer la phrase par un nom de fonction enfreint une règle anglaise dont je ne suis pas au courant. Edit: Je remercie vraiment tout le monde pour ces réponses. Ils ont changé et amélioré ma compréhension de la question. J'ai beaucoup appris de cela. Je suis très surpris de ne pas avoir pensé à ces solutions simples mais bonnes.

Je pense vraiment que ma position en alternance était trop difficile et je me rends compte maintenant, grâce à ces bonnes réponses, que la modification de la phrase semble être la meilleure option pour traiter ces cas, que ce soit en ajoutant une parenthèse après la fonction ou en disant La fonction avant le nom de la fonction et, si disponible, en utilisant le formatage pour le nom de la fonction.

functions utilisateur3462295
la source
1
@gnat je ne demande pas quoi nommer quelque chose, je demande comment commencer une phrase avec un nom de fonction.
user3462295
13
Il existe une convention connexe en mathématiques selon laquelle il convient d'éviter de commencer une phrase avec un nom de variable ou une formule. Ceci en dépit du fait que nous avons une convention typographique selon laquelle les variables et les formules sont affichées en italique pour les différencier du texte. On éviterait d'écrire "Soit x une puissance de 2. x est positif, donc ..." La solution habituelle consiste à reformuler ou à ajouter un mot clé: " x est positif" ou "nous avons x est positif" ou quelque chose de la sorte.
Nate Eldredge
9
Un identifiant d'un langage de programmation doit être traité comme un mot étranger et ne doit pas être soumis aux mêmes règles de l'anglais.
Rufflewind le
1
Il y a des programmeurs remarquablement actifs en anglais.SE ( tchrist ... pas tellement Eric Lippert ) - mais cela dépend du type de réponse que vous souhaitez. Nous écrivons ceci en tant que programmeurs sur un site dédié aux programmeurs. Si vous êtes plus intéressé par les formalités de rédaction technique, les directives de journal et la structure de phrase en anglais appropriée, vous voudrez peut-être reconsidérer votre public cible d'experts.
2
Cette question semble être hors sujet parce que c'est la langue anglaise et son utilisation, et nous avons un site StackExchange complet pour cela. En effet, il y a au moins quatre semblables des questions là - bas . De plus, différentes réponses peuvent être également valables selon le lieu où figure l'écriture, etc.
Caleb

Réponses:

87

En typographie, ceci est généralement traité en utilisant un rendu différent, qu'il s'agisse ou non du début d'une phrase, pour indiquer que ce qui frappe l'œil n'est pas simplement un mot dans la phrase, mais une entité spéciale.

Votre freadimplémentation est cassée. freaddoit retourner combien d'octets ont été lus.

Selon la forme du document, il peut adopter la même approche. Dans tous les cas, cela élimine le problème que vous identifiez et vous voudrez peut-être l'utiliser uniquement pour cette raison.

Dans le monde du texte brut (comme indiqué par plusieurs commentaires et autres réponses), l’ajout de parenthèses aux noms de fonctions aide un peu, mais comme nous devons également faire référence à des entités qui ne prennent pas de parenthèses, cela n’a qu’une valeur limitée. En général, à moins d'adopter une convention d'encadrement du texte avec des caractères spéciaux tels que des crochets et des astérisques, dans le monde du texte en clair, il n'y a pas d'autre choix que de contourner le problème en restructurant la phrase.

Reg Modifier
la source
Oui, je vois ce que vous dites, il est quand même tombé gênant mais moins gênant. Cependant, je comprends que les sentiments ne sont pas toujours conformes aux règles de la grammaire et de l’écriture. Je ne suis pas sûr s'il existe une meilleure façon de gérer cela, donc je vais accepter votre réponse à moins que quelqu'un ne propose quelque chose de mieux.
user3462295
25
Souvent, je me contente de mettre en italique des choses comme celle-ci - vous devriez toujours conserver la casse des termes sensibles à la casse, peu importe où ils se trouvent dans une phrase, IMO. freadn'est pas un mot; c'est un symbole représentant une entité. Ce n'est pas sujet à la grammaire.
Ant P
4
Et ... que faites-vous si vous devez traiter du texte brut? Comme dans un petit fichier d’aide .txt ou un email en texte brut? Je suggère d'inclure également ce scénario dans votre réponse.
Ellesedil
2
@Ellesedil Dans ce cas, je vais généralement le remplacer par ()ou (...)pour indiquer que c'est une fonction. Mais cela ne fonctionne pas toujours, surtout lorsqu'il s'agit de variables et autres. Ce que je fais alors, c'est envelopper le nom avec `(coche) pour indiquer son code.
Cole Johnson
4
@Ellesedil J'ai commencé à utiliser la syntaxe de démarquage pour indiquer les éléments de code, même dans des contextes en texte brut tels que des commentaires. C’est la seule fois où j’ai eu besoin d’utiliser un symbole de coup de pouce lorsque j’écris en anglais clair.
Keen
53

S'il est absolument nécessaire de commencer chaque phrase avec un plafond, remplacez-le simplement freadpar "La freadfonction" partout où il commence une phrase.

x-code
la source
21

Si vous n'avez pas de moyen typographique pour distinguer (comme dans une autre réponse), et peut-être même si c'est le cas, il peut être utile d'indiquer que vous parlez d'une fonction en utilisant des parens:

Votre implémentation fread () est cassée. fread () doit retourner combien d'octets ont été lus.

Cela aide à "expliquer" pourquoi il n'est pas capitalisé au début de la deuxième phrase, et aide également (dans la première phrase) à comprendre pourquoi le nom propre (nom d'une fonction) n'y est pas capitalisé non plus . Depuis (en tant que nom propre), cela aurait sans doute dû l'être.

("discutablement" parce que nous pourrions discuter si fread () est un nom générique ou un nom propre).

Dans l'ensemble, l'utilisation de parens aide le cerveau du lecteur à comprendre pourquoi des mots étranges apparaissent et ce qu'ils sont.

GreenAsJade
la source
5
L'utilisation de parens permet également de réduire la redondance du texte. Au lieu de "la fonction fread", vous pouvez simplement dire "fread ()". Et il est également utile si vous avez une sorte de mise en surbrillance pour souligner la différence entre les noms de variables et les fonctions.
Paul92
3
Je pense que les parenthèses ne font qu'ajouter plus de confusion. fread()pourrait être une déclaration d'appel. Ou il pourrait s'agir d'une fonction surchargée sans paramètre.
Kapex
4
@kapep Généralement, dans les documents faisant référence à du code, func_name()est lu comme "une fonction du nom func_name", que la fonction elle-même ait ou non des paramètres.
Eric Finn
3
@EricFinn D'après mon expérience, il fait généralement référence à des fonctions sans paramètre, mais cela dépend sûrement du langage et de ses conventions. Par exemple, les directives officielles sur les commentaires Java découragent l'utilisation de parenthèses: "Lorsque vous vous référez à une [forme spécifique d'une méthode], utilisez des parenthèses et des types d'argument. [...] Toutefois, si vous faites référence aux deux formes de la méthode, omettez Il est trompeur d'inclure des parenthèses vides, car cela impliquerait une forme particulière de la méthode " oracle.com/technetwork/java/javase/documentation/…
kapex
3
Bien que l’ajout d’un indice visuel soit certainement une bonne idée (le mieux étant une police dédiée ou une autre mise en évidence), mais je suis d’accord avec Kapep pour dire que l’ajout de parens vides est un choix vraiment problématique, car dans chaque langue que je connais f()signifie autre chose f. Pourquoi ne pas entourer le nom d’un caractère approprié, par exemple un "fread" de style markdown (c’est ce que j’ai tendance à faire dans les messages de validation de VCS)? Ou simplement (fread). Bien sûr, une telle chose devrait être faite de manière cohérente, pas seulement pour les fonctions au début d'une phrase.
leftaroundabout
10

Vous pouvez commencer une phrase à partir de la description:

La fonction fread[…]

La méthode fread[…]

La propriété breadColor[…]

David Sergey
la source
@ Zack: le président Obama.
Marc van Leeuwen
@MarcvanLeeuwen Les titres sont un cas particulier. (Également "Queen Elizabeth", "Mister Rogers".) Je n'ai pas d'analyse appropriée, mais intuitivement, je pense qu'ils sont considérés comme faisant partie du nom plutôt que d'une étiquette de catégorie.
dimanche
8

Vous pouvez comparer cela aux mathématiques intégrées dans les publications. Vous verrez très rarement des phrases commençant par une variable ou d’autres mathématiques en ligne.

Je conclus donc que vous devriez éviter les noms de fonction au début d'une phrase.

Peut-être que cette question fournit des détails supplémentaires: Peut-on commencer une phrase avec une lettre grecque (variable)? .

Lukas
la source
3
+1 Dans Mathematical Proofs (Chartrand et al., 2000), dont le chapitre 0 est une véritable source de bons conseils pour l’écriture mathématique, la toute première règle sous Utilisation de symboles est "Ne commencez jamais une phrase par un symbole". (L'exemple est une phrase qui commence par une équation; les auteurs suggèrent de la faire précéder de "L'équation ___".) Bien que tous les conseils d'écriture mathématique ne s'appliquent pas nécessairement à l'écriture sur le code source, je pense que c'est un bit qui le fait.
Ruakh
1
Je ne suis pas sûr d'être d'accord avec l'analogie. Des symboles comme $ x $ sont transitoires dans une équation, il est donc étrange de s'y référer comme s'ils avaient une signification globale. Si un symbole comme $ \ pi $ commence une phrase, je me sentirais à l'aise en tant que lecteur.
Djechlin
1
@djechlin Je ne suis pas sûr que commencer une phrase avec un symbole implique que cela ait un sens global, ou en fait quelque chose à voir avec cela.
Kyle Strand
@KyleStrand, il serait bon de savoir pourquoi vous ne devriez jamais commencer une phrase avec un symbole. "$ \ pi $ est ..." v. "La constante mathématique $ \ pi $ est ..." - vous choisissez.
Djechlin
1
@djechlin: Une des raisons est que si la phrase précédente se termine par un calcul, le calcul au début de la phrase suivante peut sembler faire partie de la même formule avec un point entre les deux. (C'est encore plus un problème avec les virgules.) Un autre problème est que, comme les noms de variables sont généralement en minuscules, le lecteur perd le repère visuel qui consiste à rechercher une lettre majuscule pour trouver le début de la phrase suivante.
Nate Eldredge
3

La page de manuel Linux de fread (3) , mise en lien par d’autres, est un excellent exemple de quatre solutions courantes.

  1. Commencez votre phrase par "La fonction foo" ou "La fonction foo". "La fonction fread doit retourner ..." .
  2. Marquez le nom de la fonction avec des caractères supplémentaires conformément à la convention utilisée par votre communauté de langage de programmation. Dans le cas de C, une paire de parenthèses vide, donc "fread () doit renvoyer ..." .
  3. Utilisez une typographie (gras, caractères de largeur fixe ou italique) pour mettre en surbrillance le nom de la fonction, ainsi: "le fil doit retourner ..."
  4. Sur les systèmes utilisés man, si votre fonction comporte une page de manuel, reportez-vous au chapitre du manuel entre parenthèses. Donc "fread (3) doit revenir ..."

Les quatre approches seront immédiatement reconnaissables par les pirates, et vous devriez pouvoir en choisir une qui correspond à votre style personnel ou à votre voix personnelle.

Comme vous l'avez dit, vous ne pouvez pas compter sur la typographie pour mettre en évidence le nom de votre fonction. La syntaxe de Markdown est conçue pour rendre la documentation lisible même lorsqu'un interprète de démarquage n'est pas disponible. Entourez donc votre nom de fonction par une paire de backticks. (Ceci est, je suppose, une combinaison des options 2 et 3.)

L'option 2 varie selon le langage de programmation. Par exemple, les documents Ruby et Smalltalk précèdent souvent les noms de méthodes d'instance avec un hachage, comme #fread . Pendant ce temps, les liseurs pourraient préférer que le nom de la fonction soit nu, mais comprendront si vous écrivez un appel à une fonction squelette, tel que (fread ...) ou (fread) . Rincez et répétez pour toutes les langues que vous documentez.

faire du travail
la source
J'aime votre réponse. Faire cela rendrait mieux écrire sur les fonctions.
user3462295
2

Je ne vais répondre que pour l'exemple spécifique donné:

Votre implémentation de fread est cassée. fread doit renvoyer le nombre d'octets lus.

Il suffit de remplacer le premier point (Période) par un point-virgule:

Votre implémentation de fread est cassée; fread doit renvoyer le nombre d'octets lus.

EdHunter
la source
3
Non! cela en ferait une phrase superflue ou une séparation par virgule. Très mauvaise grammaire. Un point-virgule serait OK.
Martin McCallion
Donc, utiliser une virgule ne fonctionne pas toujours; mais pourquoi utiliser une virgule?
reinierpost
Ce n'est pas une virgule. C'est un point-virgule; un bon usage d'un point-virgule à cela.
RubberDuck
1
Personnellement, je voudrais utiliser un colon ici au lieu d'un point-virgule (même s'il se lit bien aussi avec un point-virgule).
Marc van Leeuwen
0

Je sais que cela a déjà été répondu, et la réponse acceptée est très bonne, mais je veux juste clarifier quelque chose.

La grammaire anglaise est la suivante: parfois, les noms propres se voient attribuer des noms qui ne commencent pas par une lettre majuscule, et dans la plupart des cas, ils sont tout aussi attachés au fait de ne pas être capitalisés que les noms propres "normaux" être capitalisé. Dans de tels cas - qui incluraient certainement la plupart des noms de fonctions dans les langues C descendues - vous ne mettez absolument pas le nom en majuscule, même au début d'une phrase. En fait, c'est une mauvaise grammaire et orthographe anglaise de le faire. C'est en fait une partie du même principe qui explique pourquoi il est correct d'épeler la console de jeu de Sony "PlayStation", mais pas "Playstation".

Il existe d'autres cas dans lesquels un nom propre n'est pas censé être mis en majuscule par défaut et pourtant il peut l'être (et devrait l'être) lorsqu'il est utilisé au début d'une phrase. Le nom de la langue brainfuck en est un exemple. Les fonctions dans les langues en C descendant ne le sont pas. myFunc()et MyFunc()sont deux choses totalement différentes dans des langues comme ça, et commencer une phrase avec le mot "MyFunc ()" ne fera que se référer à la dernière, pas à la première. Toutefois, dans VB.NET, il s’agit d’une zone grise, car ces deux fonctions seraient identiques dans cette langue, bien que les noms de fonction conservent également des schémas de capitalisation spécifiés par l’utilisateur, à un niveau ou à un autre.

De plus, même si les règles anglaises sont immuables dans ce cas, elles ont tendance à être plutôt floues autour de choses comme celle-ci. L’anglais n’a pas été conçu avec ce genre de choses à l’esprit, alors il ya de la place pour l’improvisation.

Panzercrisis
la source