Quelqu'un d'autre trouve-t-il que les classes et les méthodes de nommage constituent l'une des parties les plus difficiles de la programmation?
Je travaille donc sur cette classe qui est supposée demander de la documentation d'aide à un fournisseur via un service Web. J'essaie de le nommer DocumentRetriever, VendorDocRequester, DocGetter, mais ça ne sonne pas juste. J'ai fini par parcourir dictionary.com pendant une demi-heure à essayer de trouver un mot adéquat.
Commencer à programmer avec de mauvais noms, c'est comme avoir une très mauvaise journée le matin, le reste de la journée s'estompant à partir de là. Me sentir?
Ce que vous faites maintenant va bien, et je vous recommande vivement de conserver votre syntaxe actuelle, à savoir:
contexte + verbe + comment
J'utilise cette méthode pour nommer des fonctions/méthodes, des procs stockées SQL, etc. En respectant cette syntaxe, vos volets de code Intellisense/Code seront beaucoup plus soignés. Donc, vous voulez EmployeeGetByID () EmployeeAdd (), EmployeeDeleteByID (). Lorsque vous utilisez une syntaxe plus grammaticalement correcte, telle que GetEmployee (), AddEmployee (), vous constaterez que cela devient vraiment compliqué si vous avez plusieurs Gets dans la même classe, car des éléments non liés seront regroupés.
Cela ressemble à nommer des fichiers avec des dates, vous voulez dire 2009-01-07.log pas le 1-7-2009.log, car après que vous en avez plusieurs, la commande devient totalement inutile.
Une bonne convention de dénomination devrait minimiser le nombre de noms possibles que vous pouvez utiliser pour une variable, une classe, une méthode ou une fonction donnée. S'il n'y a qu'un seul nom possible, vous n'aurez jamais de difficulté à vous en souvenir.
Pour les fonctions et pour les classes singleton, je scrute la fonction pour voir si sa fonction de base est de transformer un genre de chose en un autre genre de chose. J'utilise ce terme très vaguement, mais vous découvrirez qu'un très grand nombre de fonctions que vous écrivez prennent essentiellement quelque chose sous une forme et produisent quelque chose sous une autre forme.
Dans votre cas, cela ressemble à votre classe transforme une URL en Document. C'est un peu bizarre de penser de cette façon, mais c'est tout à fait correct, et lorsque vous commencez à rechercher ce motif, vous le voyez partout.
Quand je trouve ce modèle, je nomme toujours la fonction xFromy.
Depuis votre fonction transforme une URL en un document, je l'appellerais
DocumentFromUrl
Ce modèle est remarquablement commun. Par exemple:
atoi -> IntFromString
GetWindowWidth -> WidthInPixelsFromHwnd // or DxFromWnd if you like Hungarian
CreateProcess -> ProcessFromCommandLine
Vous pouvez également utiliser UrlToDocument si vous êtes plus à l'aise avec cet ordre. Que vous disiez xFromy ou yTox est probablement une question de goût, mais je préfère l’ordre From parce qu’ainsi le début du nom de la fonction vous indique déjà le type qu’elle renvoie.
Choisissez une convention et respectez-la. Si vous veillez à utiliser les mêmes noms que vos noms de classes dans vos fonctions xFromy, il sera beaucoup plus facile de vous rappeler quels noms vous avez utilisé. Bien sûr, ce modèle ne fonctionne pas pour tout, mais cela fonctionne lorsque vous écrivez un code que vous pouvez considérer comme "fonctionnel".
Une leçon que j'ai apprise est que si vous ne pouvez pas trouver un nom pour une classe, il y a presque toujours un problème avec cette classe:
- tu n'en as pas besoin
- ça fait trop
Parfois, il n’ya pas un bon nom pour une classe ou une méthode, cela nous arrive à tous. Souvent, cependant, l’impossibilité de trouver un nom peut laisser présager un problème avec votre conception. Votre méthode a-t-elle trop de responsabilités? Votre classe encapsule-t-elle une idée cohérente?
Fil 1:
function programming_job(){
while (i make classes){
Give each class a name quickly; always fairly long and descriptive.
Implement and test each class to see what they really are.
while (not satisfied){
Re-visit each class and make small adjustments
}
}
}
Fil 2:
while(true){
if (any code smells bad){
rework, rename until at least somewhat better
}
}
Il n'y a pas de Thread.sleep (...) nulle part ici.
Je passe également beaucoup de temps à m'inquiéter des noms de tout ce qui peut être nommé lors de la programmation. Je dirais que cela rapporte très bien cependant. Parfois, quand je suis coincé, je le laisse pour un moment et pendant une pause-café, je demande un peu si quelqu'un a une bonne suggestion.
Pour votre classe, je suggérerais VendorHelpDocRequester.
Le livre Code Complete de Steve Mcconnell contient un chapitre intéressant sur le nommage des variables/classes/fonctions/...
Je pense que c'est un effet secondaire.
Ce n'est pas difficile de nommer. Ce qui est difficile, c’est que le processus de désignation vous oblige à faire face au fait horrible que vous n’avez aucune idée de ce que vous faites.
En fait, je viens d’entendre cette citation hier, à travers le blog Signal vs. Noise de 37Signals, et je suis tout à fait d’accord avec elle:
"Il n’ya que deux choses difficiles en informatique: l’invalidation de la mémoire cache et la dénomination." - Phil Karlton
C'est bien que c'est difficile. Cela vous oblige à réfléchir au problème et à ce que la classe est réellement supposée faire. De bons noms peuvent aider à mener à un bon design.
J'écrivais juste sur les conventions de nommage le mois dernier: http://caseysoftware.com/blog/useful-naming-conventions
L'essentiel:
verbAdjectiveNounStructure - avec structure et adjectif comme pièces facultatives
Pour les verbes , je m'en tiens aux verbes d'action: enregistrer, supprimer, notifier, mettre à jour ou générer. De temps en temps, j'utilise "processus", mais uniquement pour faire référence à des files d'attente ou à des retards de travail.
Pour noms , j'utilise la classe ou l'objet avec lequel on interagit. Dans web2project, il s'agit souvent de tâches ou de projets. Si c'est Javascript qui interagit avec la page, il peut s'agir d'un corps ou d'une table. Le fait est que le code décrit clairement l'objet avec lequel il interagit.
La structure est facultative car unique à la situation. Un écran de liste peut demander une liste ou un tableau. L'une des fonctions principales utilisées dans la liste de projets pour web2project est simplement getProjectList. Il ne modifie pas les données sous-jacentes, mais seulement la représentation des données.
Les adjectifs sont complètement différents. Ils sont utilisés comme modificateurs du nom. Quelque chose d'aussi simple que getOpenProjects peut être facilement implémenté avec un paramètre getProjects et switch, mais cela a tendance à générer des méthodes qui nécessitent un peu de compréhension des données sous-jacentes et/ou de la structure de l'objet ... pas nécessairement quelque chose que vous voulez. encourager. En ayant des fonctions plus explicites et spécifiques, vous pouvez complètement encapsuler et masquer l'implémentation du code qui l'utilise. N'est-ce pas l'un des points d'OO?
D'accord. J'aime que mes noms de types et mes variables soient aussi descriptifs que possible sans être trop longs, mais parfois, il existe un certain concept pour lequel vous ne pouvez pas trouver un bon mot.
Dans ce cas, cela m’aide toujours de demander l’avis d’un collègue - même s’ils ne l’aident pas en fin de compte, cela m’aide généralement au moins de l’expliquer à voix haute et de faire tourner mes roues.
En bref:
Je conviens que les bons noms sont importants, mais je ne pense pas que vous deviez les trouver avant de les utiliser à tout prix.
Bien sûr, il vaut mieux avoir un bon nom dès le début. Mais si vous ne parvenez pas à en créer un en 2 minutes, renommer plus tard coûtera moins de temps et constitue le bon choix du point de vue de la productivité.
Long:
Généralement, il ne vaut souvent pas la peine de trop réfléchir à un nom avant de le mettre en œuvre. Si vous implémentez votre classe, appelez-la "Foo" ou "Dsnfdkgx", tout en implémentant, vous verrez ce que vous auriez dû nommer.
En particulier avec Java + Eclipse, renommer des objets ne pose aucun problème, car il gère soigneusement toutes les références dans toutes les classes, vous met en garde contre les collisions de noms, etc. Et tant que la classe n'est pas encore dans le référentiel de contrôle de version, je ne le fais pas. t pense qu'il y a quelque chose de mal à le renommer 5 fois.
Fondamentalement, il s’agit de savoir comment vous pensez de la refactorisation. Personnellement, j'aime bien, bien que cela agace parfois mes coéquipiers, car ils croient en jamais toucher un système en marche . Et parmi tout ce que vous pouvez refactoriser, changer de nom est l’une des choses les plus inoffensives que vous puissiez faire.
Mieux que nommer une classe, créer une structure de paquetage appropriée peut être un défi difficile mais gratifiant. Vous devez envisager de séparer les préoccupations de vos modules et leur lien avec la vision de l'application.
Considérez la mise en page de votre application maintenant:
- App
- VendorDocRequester (lu à partir du service Web et fournit des données)
- VendorDocViewer (utilisez requester pour fournir la documentation du fournisseur)
J'oserais supposer qu'il se passe beaucoup de choses dans quelques classes. Si vous deviez reformuler cela dans une approche plus axée sur MVC et permettre à de petites classes de gérer des tâches individuelles, vous pourriez vous retrouver avec quelque chose comme:
- App
- VendorDocs
- Modèle
- Document (objet brut contenant des données)
- WebServiceConsumer (traiter avec Nitty Gritty dans le service Web)
- Manette
- DatabaseAdapter (gérer la persistance à l'aide d'ORM ou d'une autre méthode)
- WebServiceAdapter (utilisez Consumer pour saisir un document et le coller dans une base de données)
- Vue
- HelpViewer (utilisez DBAdapter pour cracher la documentation)
Ensuite, vos noms de classe s'appuient sur l'espace de noms pour fournir un contexte complet. Les classes elles-mêmes peuvent être intrinsèquement liées à l'application sans avoir à le dire explicitement. Les noms de classe sont donc plus simples et plus faciles à définir!
Une autre suggestion très importante: faites-vous une faveur et procurez-vous un exemplaire de Head First Design Patterns. C'est un livre fantastique et facile à lire qui vous aidera à organiser votre application et à écrire un meilleur code. Apprécier les modèles de conception vous aidera à comprendre que de nombreux problèmes que vous rencontrez ont déjà été résolus et vous pourrez incorporer les solutions dans votre code.
Leo Brodie, dans son livre "Thinking Forth", écrivait que la tâche la plus difficile pour un programmeur était de bien nommer les choses, et il a déclaré que l'outil de programmation le plus important était un thésaurus.
Essayez d’utiliser le thésaurus à l’adresse http://thesaurus.reference.com/ .
Au-delà, n'utilisez JAMAIS la notation hongroise, évitez les abréviations et restez cohérent.
Meilleurs vœux.
Il n'y a qu'un seul nom raisonnable pour cette classe:
HelpRequest
Ne laissez pas les détails de la mise en œuvre vous distraire du sens.
Pourquoi ne pas aider HelpDocumentServiceClient, ou HelpDocumentClient ... peu importe qu'il s'agisse d'un fournisseur, il s'agit d'un client d'un service Web qui traite des documents d'aide.
Et oui, nommer est difficile.
Pour moi, je ne me soucie pas de savoir combien de temps une méthode ou un nom de classe est aussi long que son descriptif et dans la bonne bibliothèque. L'époque où vous devriez vous souvenir de chaque partie de l'API est révolue.
Intelisense existe pour toutes les langues principales. Par conséquent, lorsque j'utilise une API tierce, j'aime utiliser intelisense pour la documentation, par opposition à la documentation "réelle".
Dans cet esprit, je vais bien pour créer un nom de méthode tel que
StevesPostOnMethodNamesBeingLongOrShort
Long - mais alors quoi. Qui n'utilise pas les écrans 24 pouces ces jours-ci!
Investissez dans un bon outil de refactoring!
Je m'en tiens à l'essentiel: VerbNoun (arguments). Exemples: GetDoc (docID).
Il n'y a pas besoin de fantaisie. Ce sera facile à comprendre dans un an, que ce soit vous ou quelqu'un d’autre.
Non, le débogage est la chose la plus difficile pour moi! :-)
La documentation du fournisseur ne devrait-elle pas être l'objet? Je veux dire, celui-là est tangible, et pas seulement comme une anthropomorphisation d’une partie de votre programme. Vous pouvez donc avoir une classe VendorDocumentation avec un constructeur qui récupère les informations. Je pense que si un nom de classe contient un verbe, quelque chose a mal tourné.
Je dois convenir que nommer est un art. Cela devient un peu plus facile si votre classe suit un certain "schéma de desigh" (usine, etc.).
Le langage que vous utilisez pour décrire le problème est le langage que vous devez utiliser pour les variables, méthodes, objets, classes, etc. En gros, les noms correspondent aux objets et les méthodes de correspondance des verbes. S'il manque des mots pour décrire le problème, il vous manque également une compréhension complète (spécification) du problème.
S'il ne s'agit que de choisir entre un ensemble de noms, il doit être régi par les conventions que vous utilisez pour construire le système. Si vous êtes arrivé à un nouvel endroit, non couvert par les conventions précédentes, alors il vaut toujours la peine de déployer des efforts pour essayer de les étendre (correctement, régulièrement) pour couvrir ce nouveau cas.
En cas de doute, dormez dessus et choisissez le premier nom le plus évident, le lendemain matin :-)
Si vous vous réveillez un jour et réalisez que vous aviez tort, changez-le immédiatement.
Paul.
BTW: Document.fetch () est assez évident.
Je trouve que j'ai le plus de problèmes avec les variables locales. Par exemple, je veux créer un objet de type DocGetter. Donc, je sais que c'est un DocGetter. Pourquoi dois-je lui donner un autre nom? Je finis généralement par lui donner un nom comme dg (pour DocGetter) ou temp ou quelque chose d’autre non descriptif.
N'oubliez pas que les modèles de conception (pas uniquement ceux du GoF) constituent un bon moyen de fournir un vocabulaire commun et que leurs noms doivent être utilisés chaque fois que l'on convient à la situation. Cela aidera même les nouveaux arrivants qui connaissent la nomenclature à comprendre rapidement l’architecture. Ce cours sur lequel vous travaillez est-il censé se comporter comme un proxy ou même une façade?
C'est l'une des raisons pour lesquelles une norme de codage est utilisée. Avoir une norme a tendance à aider à trouver des noms au besoin. Cela aide à libérer votre esprit pour utiliser d'autres choses plus intéressantes! (-:
Je vous recommande de lire le chapitre correspondant du Code Complete de Steve McConnell ( lien Amazon ), qui décrit plusieurs règles pour améliorer la lisibilité et même la maintenabilité.
HTH
à votre santé,
Rob
DocumentFetcher? C'est difficile à dire sans contexte.
Il peut être utile d’agir comme un mathématicien et d’emprunter/d’inventer un lexique pour votre domaine au fur et à mesure: choisissez des mots simples et concis qui suggérez le concept sans l’épeler à chaque fois. Trop souvent, je vois de longues phrases latines qui se transforment en acronymes, ce qui vous oblige à utiliser un dictionnaire pour les acronymes en tout cas.
Je te sens vraiment. Et je ressens ta douleur. Chaque nom auquel je pense me semble tout simplement nul. Tout cela semble si générique et je souhaite apprendre à intégrer un peu de talent et de créativité à mes noms, afin qu'ils reflètent réellement ce qu'ils décrivent.
Une suggestion que j'ai est de consulter un thésaurus. Word en a une bonne, de même que Mac OS X. Cela peut vraiment m'aider à sortir la tête des nuages et à me donner un bon point de départ et une source d'inspiration.
Lorsque chaque nom sensible semble trop long ou ambigu, vous pouvez essayer d’utiliser quelque chose un peu moins sensible, par exemple:
- classe GoForHelpLassie
- classe DunnoAskTechSupport
- classe RTFVM [où V est pour le vendeur]
Assurez-vous que le nom est vraiment unique et qu'il y a un commentaire descriptif en haut de la classe, car quiconque le verra dans le code devra le rechercher pour savoir ce qu'il fait ( mais quand ils le feront, ils trouveront probablement plus facile de se souvenir).
Si le nom s’explique lui-même à un programmeur profane, il n’est probablement pas nécessaire de le changer.
Ce que je fais est de vérifier si c'est trop long si je ne me souviens pas trop longtemps
Je ne trouve pas ça difficile Si vous ne pouvez pas le nommer, alors vous n'en avez peut-être pas besoin. Plus votre conception est efficace, plus il sera facile de nommer les éléments que votre conception fait.
Maintenant, les variables temporaires, c'est une autre histoire. :)
Eh bien, je le vois sous un autre angle, c’est l’une des choses les plus importantes si vous voulez que votre code soit lisible par d’autres.
Essayez de le rendre descriptif et s'il provient d'un tiers, pourquoi ne pas inclure le nom [du tiers] dans le nom de la classe ou de la méthode.
Si cela prend trop de temps, utilisez n'importe quel nom, vous pouvez le changer après.
Si 8 personnes sur 10 le comprennent, vous pouvez supposer en toute sécurité qu'il est compréhensible, lisible et clair. Il y aura toujours ces ramasseurs 1 ou 2 nuls qui essaieront de vous reprocher sans autre raison que leur maigreur.
Je trouve qu'il est plus facile de choisir un nom une fois que quelque chose est fini. Refactor> Renommer ftw.
Une autre raison pour laquelle chaque développeur de logiciel devrait avoir des compétences en écriture et en communication.
PD: Je pense qu'un vocabulaire étendu est également important.
Résumez simplement la méthode/classe dans "Un mot", en répondant à sa signification. Et il ne devrait y avoir aucun équivalent pour cette Parole.
Je ressens ta douleur. : /
J'aimerais qu'il existe un outil permettant de réviser le code source en conjonction avec un dictionnaire de données (un fichier décrivant les différents noms de variables/méthodes, un peu comme javadoc), afin que vous puissiez écrire du code comme celui-ci:
class Battery
{
double I; // current
double T; // temperature
double V; // voltage
double Q; // charge
void update(double Inew, double dt) { I = Inew; Q += I*dt; }
// ... etc ...
};
et l'outil de révision de code pourrait effectuer un certain nombre de choses différentes pour faciliter la visualisation du code en contexte, y compris l'affichage de rappels indiquant que I = actuel (par exemple, dans un volet situé à droite de la fenêtre, il afficherait les définitions de variable)./sémantique/commentaires pour la place dans le code sur lequel vous cliquez), ou même vous autoriser à faire du "refactoring virtuel" où en tant que réviseur de code, vous pouvez renommer quelque chose à votre goût pour des raisons de lisibilité/affichage sans changer réellement le code stocké disque.
Bien que j'aime les noms auto-descriptifs, je déteste lire des choses comme BatteryFilteredCurrentInMilliamps. Souvent, dans les systèmes embarqués, nous modélisons des objets basés sur des équations algébriques et les noms comme ceux-ci deviennent très lourds. (Par contre, un "I" avec un chapeau sur le dessus et un indice "d" et un indice "*" est assez déroutant.)
Je suis d'abord un ingénieur EE/systèmes avec des responsabilités logicielles mineures et au final, je ne me soucie vraiment pas du nom d'une variable tant que j'ai un moyen pratique de le dire et de le mapper dans mon propre modèle interne. du système contrôlé.
Cela me semble généralement très naturel. Je fais toujours des méthodes très courtes, jamais plus de 6 lignes de code Smalltalk (automatiquement mises en forme), je n'ai donc aucun problème à dire en quoi consiste cette méthode.
Parfois, les noms de classe sont difficiles, car le mot que je veux choisir est utilisé quelque part dans le système, car parfois le même mot a des significations différentes dans des contextes distincts. Je souhaite que dans ces cas, une syntaxe semblable à celle de Wikipedia soit autorisée, afin que je puisse nommer ma classe "Task (To do list item)". En attendant que cela soit légal, j'en fais un grand mot de style allemand: ToDoListItemTask. Vous l'avez peut-être deviné: les noms de méthodes peuvent être très longs, aussi. Mais je pense qu'ils sont lisibles.
Donc, dans votre cas, votre classe est un "getter", un retriever ou autre chose. Êtes-vous sûr que cela devrait être modélisé en classe? Le fournisseur ne devrait-il pas pouvoir se demander lui-même? Quelque chose comme vendorDoc.requestFrom (source); serait plus facile à nommer, n'est-ce pas?
à votre santé,
niko
Pas vraiment. Considérant toutes les choses difficiles à comprendre en codage, affirmer que nommer des classes et des méthodes est l’une des choses les plus difficiles en programmation est absurde. Ne vous méprenez pas, il est parfois difficile de trouver un bon nom, mais soyons vrais ici. J'irai jusqu'à dire que c'est l'une des parties les plus faciles de la programmation.