Consignes de dénomination des méthodes concises significatives

Récemment, j'ai commencé à publier un projet open source, alors que j'étais le seul utilisateur de la bibliothèque, je ne me souciais pas des noms, mais je sais que je veux attribuer des noms intelligents à chaque méthode pour le rendre plus facile à apprendre, mais je dois également utiliser des noms concis afin qu'ils soient également faciles à écrire.

Je pensais à quelques lignes directrices sur la dénomination, je connais beaucoup de lignes directrices qui ne se soucient que de la casse des lettres ou de quelques notes simples. Ici, je suis à la recherche de directives pour une dénomination significative mais concise.

Par exemple, cela pourrait faire partie des lignes directrices dont je m'occupe:

• Utilisez Ajouter quand un élément existant va être ajouté à une cible, Utilisez Créer quand un nouvel élément est créé et ajouté à une cible.
• Utilisez Supprimer lorsqu'un élément existant va être supprimé d'une cible, Utilisez Supprimer lorsqu'un élément va être supprimé définitivement.
• Jumelez les méthodes AddXXX avec RemoveXXX et Jumelez les méthodes CreateXXX avec les méthodes DeleteXXX, mais ne les mélangez pas.

Comme le montrent les exemples ci-dessus, je voudrais trouver du matériel en ligne qui m'aide avec les méthodes de dénomination et d'autres éléments conformes à la grammaire anglaise et aux significations des mots.

Les conseils ci-dessus peuvent être intuitifs pour les anglophones natifs, mais pour moi, l'anglais est ma deuxième langue, je dois être informé de choses comme ça.

Appellation. L'une des choses les plus difficiles sur le développement de logiciels :)

Lorsque je nomme quelque chose, voici mon ensemble de priorités:

• Suivez les idiomes de ma langue. Ruby aime les soulignés. Javascript aime les étuis à chameaux. Quelle que soit la langue dans laquelle vous vous trouvez, c'est la convention à suivre.
• Révèle l'intention de l'API. Ce n'est pas "send_http_data" c'est "post_twitter_status"
• Évitez de divulguer les détails de mise en œuvre. Disons, préfixant une variable avec un type.
• N'utilise pas plus de caractères que nécessaire sans enfreindre les directives précédentes.

C'est évidemment une approche assez simpliste. La dénomination est nuancée.

Pour de plus amples recherches, je recommanderais de lire The Art of Readable Code , car il fournit d'excellents conseils succincts sur la dénomination des méthodes. Pour encore plus de recherches, je ne peux que recommander fortement le code propre de Bob Martin

La tentation de codifier un style ou une convention de dénomination peut dans certains cas conduire à des habitudes qui sont aujourd'hui considérées comme de mauvaises pratiques, comme l'utilisation de la notation hongroise par exemple. La réponse simple est d'oublier la convention et le style de dénomination comme s'il s'agissait d'une chose distincte à déterminer séparément, et de se concentrer plutôt sur la dénomination de tout dans votre système en fonction de ce qu'il représente réellement. Les noms de méthode auront naturellement tendance à être concis si vous limitez la fonctionnalité de chaque méthode afin qu'elle ne fasse qu'une chose théoriquement, et si le nom de votre méthode décrit réellement la seule chose que la méthode est censée faire.

Les variables, les champs, les noms de classe et de fichier sont autre chose. Je suggérerais que si les noms de variables deviennent trop longs, alors vous essayez de décrire ces éléments dans un trop grand détail, ou ils représentent quelque chose de complexe qui devrait soit être divisé en parties plus petites, soit peut-être décrit de manière plus abstraite. manière.

À la fin de la journée, vous voulez éviter le code laid avec des noms qui occupent une ligne entière, ou qui sont si simples qu'ils leur volent leur valeur.

Pour moi, trouver un bon nom pour quelque chose revient toujours à le considérer comme un objet qui doit justifier son existence. Demande toi:

• Que fait la classe / méthode / variable, c'est-à-dire quel est son objectif plus large et à quoi sert-elle?
• De quoi précisément a-t-elle besoin pour communiquer, c'est-à-dire quelle est la part essentielle que le nom doit y avoir?

La plupart des développeurs conviendraient que la lisibilité est toujours d'une importance primordiale lorsqu'il s'agit de nommer. Ne vous contentez pas d'écrire du code afin de savoir ce que vous voulez dire pendant que vous l'écrivez, écrivez-le de sorte que quelqu'un qui regarde le code pour la première fois à un moment donné dans le futur sache ce que vous vouliez dire sans avoir à trop réfléchir. Vous n'écrirez le code qu'une seule fois, mais pendant sa durée de vie, il devra probablement être modifié plusieurs fois et lu encore plus de fois.

Le code doit être auto-documentéc'est-à-dire que votre nom doit rendre évident ce que fait quelque chose. Si vous avez besoin d'expliquer ce que fait une ligne de code dans un commentaire et que le changement de nom ne l'améliore pas suffisamment, vous devriez sérieusement envisager de refactoriser cette ligne dans une nouvelle méthode avec un nom descriptif approprié, afin que la lecture de la méthode d'origine, le un nouvel appel de méthode décrit ce qui se passe. N'ayez pas peur d'avoir des noms longs; bien sûr, vous ne devriez pas écrire de romans dans les noms de classe / méthode / variable, mais je préfère qu'un nom soit trop long et descriptif que trop court et j'ai besoin de comprendre ce qu'il fait en regardant sous le capot. À l'exception de quelques exceptions évidentes comme les coordonnées x / y et les acronymes couramment utilisés, évitez les noms et abréviations à un seul caractère. Appeler quelque chose "bkBtn" au lieu de "backButton"

Autant que votre langue le permet, faites lire votre code comme une phrase anglaise. Les objets utilisent des noms, les méthodes utilisent des verbes. Les méthodes booléennes commencent généralement par "est", mais il existe de nombreuses autres options qui transmettent le sens encore mieux, selon le cas d'utilisation, telles que "peut", "devrait" ou "fait". Bien sûr, toutes les langues ne peuvent pas être aussi bonnes que Smalltalk, mais certains symboles sont généralement compris comme faisant partie de la phrase. Deux conventions Smalltalk que j'aime personnellement utiliser dans d'autres langues autant que possible sont le préfixe du nom des paramètres de boucle avec "chacun", et le préfixe des paramètres de méthode avec l'article "a" (ou "an", ou "certains" pour les collections) . Ce n'est peut-être pas une norme courante en Java, et tout le monde est invité à ignorer ce bit, mais je trouve que cela améliore considérablement la lisibilité du code. Par exemple (exemple en Java):

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

Cela devrait être lisible pour les personnes ayant juste un peu de connaissance de Java comme quelque chose comme ceci:

Pour déterminer si vous devez envisager d'abréger une liste de certains noms (qui sont des chaînes), parcourez certains noms et pour chaque nom, déterminez si elle est trop longue; si oui, revenez true; si aucun n'est trop long, revenez false.

Comparez le code ci-dessus en nommant simplement l'argument stringset la variable de boucle string, en particulier dans une méthode plus complexe. Vous devriez regarder de près pour voir la différence au lieu que l'utilisation soit évidente d'un coup d'œil au nom.

Trouver un bon nom est toujours un compromis entre plusieurs facteurs. Vous ne serez jamais pleinement satisfait.

Cela dit, même si votre langue maternelle n'est pas de cette façon, considérez que l'anglais est la langue dont les jetons de langage de programmation sont formés. L'utilisation d'une syntaxe de type anglais rend la lecture de code plus "fluide" car il n'y a pas de "règles de lecture brisées" chaque fois qu'un mot clé est trouvé.

En général, considérez des choses comme object.method(parameters)correspondre à un schéma comme subject.verb(complements).

Le point clé, si vous devez prendre en charge la programmation générique, est de choisir un bon ensemble cohérent de "verbes" (en particulier ceux qui doivent être utilisés dans les algorithmes génériques).

Concernant les noms, les classes doivent être nommées pour ce qu'elles are(en terme de concept), tandis que les objets pour ce qu'elles are for.

Cela dit, entre list.add(component)et component.add_to(list)préférez le premier. En général, les verbes «transitifs actifs» représentent mieux les actions par rapport à leurs homologues passifs ou réflexifs. Sauf si le design vous contraint.

Ne vous inquiétez pas de la longueur des noms de méthode. Assurez-vous que les noms de méthode reflètent clairement ce qu'ils font. C'est primordial pour toute autre chose. Si vous pensez que le nom de la méthode est trop long, utilisez un thésaurus pour trouver un mot plus court qui signifie la même chose. Par exemple, utilisez Findau lieu de Retrieve.

Ce qui est tout aussi important, ce sont les noms que vous choisissez pour vos cours. Ceux-ci fournissent beaucoup de contexte lors de l'examen des noms de méthode. Une signature de méthode comme ceci:

public User Find(int userId);

est plus facile à comprendre que:

public Person Find(int personId);

parce que le contexte obtenu à partir du nom de classe Userindique au programmeur qui Find()est destiné à localiser un type spécifique de personne, l'utilisateur de votre système. La version qui utilise la Personclasse ne vous donne aucun contexte sur la raison pour laquelle vous auriez même besoin d'utiliser la méthode en premier lieu.

Regardez comment les autres sur votre plate-forme le font - certains des plus grands joueurs peuvent même avoir un style de code et des directives de dénomination.

Certaines plates-formes préfèrent les noms courts (par exemple, dans l'API Win32 C _tcsstrest la fonction pour trouver une chaîne dans une chaîne - n'est-ce pas évident?), D'autres vont pour la lisibilité en faveur de la brièveté (dans le cadre Cocoa d'Apple pour Objective-C , la méthode pour remplacer une sous-chaîne dans une chaîne par une autre chaîne et renvoyer le résultat lors de l'appel d'une copie stringByReplacingOccurrencesOfString: withString:). Je trouve ce dernier beaucoup plus facile à comprendre et seulement modérément plus difficile à écrire (surtout avec l'achèvement du code).

Étant donné que vous lisez le code plus souvent que vous ne l'écrivez (ce qui est doublement vrai pour les bibliothèques open source), et la lecture est plus difficile que l'écriture, optimisez pour la lecture. Optimisez pour la brièveté seulement en dernier, et enlevez autant que possible sans diluer la clarté.

1. Supposons l'anglais, à moins que tous les développeurs qui travaillent sur ce code parlent la même langue que l'anglais.

2. Étudiez les conventions et les styles de dénomination couramment acceptés. Votre principe directeur doit être la clarté. Les styles diffèrent par le langage de programmation.

3. Il n'y a rien que vous puissiez faire avec la dénomination qui facilitera la compréhension des relations entre les différents objets dans votre code. Pour cela, vous avez toujours besoin de commentaires et d'une documentation bien écrits.

1. Utilisez un préfixe. Si un tas de méthodes sont utilisées pour faire quelque chose de similaire ou peuvent être regroupées d'une manière ou d'une autre, mettez un préfixe commun devant leurs noms pour montrer ce que ces méthodes ont en commun.
2. N'utilisez pas d'abréviation peu claire si vous voulez que les autres comprennent instantanément les noms (important dans la dénomination de l'API)