10 Réponses :
Certaines stratégies:
Je pense que la chose la plus importée (si vous ne le refactez pas, cela ne va pas arriver) est de commenter et de documenter votre processus de pensée à l'époque. Cela vous aidera à rendre le code moins impénétrable et vous aidera à trouver les bons morceaux en cas de besoin.
Commentaires - Décrivez ce que vous pensais et pourquoi vous avez choisi de mettre en œuvre quelque chose d'une certaine manière, y compris quelles alternatives vous avez considérées. Il existe probablement toutes sortes de solutions de fantaisie, mais simplement en commentant votre code correctement au moment où vous écrivez semble fonctionner le meilleur.
Je ne suis pas d'accord avec toutes les réponses disant "écrire des commentaires". Cela est offert comme une prise de capture pour le code lui-même ne pas être compréhensible.
Obtenez-vous une copie de code complet (Steve McConnell, 2e édition). Si vous apprenez les techniques d'écriture de code maintenable en premier lieu, cela ne vous prendra pas plus de temps et vous pourrez retourner sur votre travail plus tard avec moins de problèmes.
Qui préféreriez-vous:
Je préfère fermement ce dernier, car le code OK est plus facile à comprendre dans les situations où le code cryptique était décalé et que des commentaires sont un autre endroit que le développeur original peut faire des erreurs. Le code peut être buggy , mais ce n'est jamais mauvais .
Une fois que vous êtes à l'aise avec code complet , je recommanderais le programmeur pragmatique , car il donne des conseils de développement logiciels légèrement supérieurs.
Oui, l'écriture de code de maintenance est très importante et je serais certainement deuxième conseil sur le code de lecture complète (je n'ai pas lu le programmateur pragmatique). Cependant, je pense toujours qu'il est important de commenter pourquoi vous avez pris les décisions que vous avez faites. Des choses comme pourquoi vous avez choisi un certain algorithme de tri sur d'autres (peut-être que vous vous attendiez à ce que les données soient partiellement triés déjà ou que cela ne soit pas plus que des enregistrements X). Les commentaires peuvent éclaircir beaucoup de "ce que diable était-ce que je pensais?" questions plus tard.
Si les commentaires pouvaient contrarier directement le code, envisagez vivement de les supprimer. Dans presque tous les cas, des commentaires ne sont utiles que lorsqu'ils fournissent des informations que vous ne pouviez pas facilement obtenir en lisant le code.
@Novelocrat je suis d'accord. Les commentaires ne sont pas le principal problème ou la solution. Je posterai mes problèmes particuliers plus en détail sous peu, mais je suis toujours intéressé par une expérience générale. (À la suite de cela, j'ai maintenant commandé CC et de commencer à plonger et d'adopter des approches proches des coûts zéro. Comme vous, je préfère le code principalement correct (ce que c'est) et que je ne suis pas inquiet pour les algorithmes difficiles Étant non motivé - ils travaillent et je donne un seul pointeur à la source générique.
En tant que corollaire beaucoup plus proche de ce que j'ai écrit ci-dessus: utilisez un système de contrôle de la version (je recommande de git ou de mercurial) religieusement . Traitez le message de validation comme votre ordinateur portable de laboratoire - Annotations critiques pour vous assurer que le travail décrit est attribuable et reproductible. Je trouve régulièrement le contenu de ces journaux plus informatif que les commentaires en ligne, car ils fournissent un contexte plus riche dans lequel les comprendre.
J'aurais fait écho à ce que les autres ont dit en ce qui concerne le commentaire de la raison pour laquelle le code a été écrit et que cela a été utilisé, mais j'ajouterais également ceci:
code comme si vous envisagiez de la mettre en production, même lorsque vous ne faites que jouer. Code pour:
En particulier, je soulignerais le premier point, mais les autres sont également importants. Je trouve que si j'utilise "code de test" plus tard, j'ai tendance à simplement l'utiliser si cela fonctionne, plutôt que de le refléter.
comme les excellentes réponses dans votre Autre message Indiquez et de ma propre expérience, il existe un écart difficile à croix entre le logiciel utilisé pour la recherche et les logiciels qui ont été conçus. À mon avis, le code complet pourrait aider un peu, mais pas beaucoup. En tant que question économique, cela visera-t-il la peine de refroidir tout pour la réutilisation par rapport à la récompense occasionnelle pour trouver une utilisation ultérieure pour quelque chose? Votre point de balance peut varier.
Voici une pointe pratique pour stocker des extraits. Au lieu de commentaires à part entière, lancez des mots-clés:
puis mettez le code quelque part google-utile, comme un compte Gmail.
EDIT: J'ajouterais que les sites Google gratuits sont vraiment consultables des wikis qui sont un bon endroit pour mettre le code, soit sous forme de pièces jointes, soit sous forme de pièces jointes ou collées.
En outre, je devrais dire que je suis un fan de code complet et j'ai donné des copies aux étudiants diplômés de la rédaction de logiciels de recherche scientifique depuis plusieurs années. C'est un bon début, mais pas de balle d'argent. J'écris un document en utilisant des cadres open source pour résoudre des problèmes de gestion des données scientifiques et que l'une des conclusions est que certaines compétences en génie logiciel sont essentielles pour les systèmes de longue date. De nombreux projets scientifiques devraient probablement budgétiser cela depuis le début.
+1 C'est une excellente idée. Si le code avait été facilement consultable (contrairement à Sourceforge où j'ai trouvé impossible la recherche), cela aurait aidé
Bon conseil, mais chaque un tel extrait devrait être défini dans le projet, dans un endroit bien en vue. Pour une personne qui dans le projet, ils sont évidents, mais pour un oureland, ils ne sont totalement pas.
Non, non, non, non, non!
N'écrivez pas de code jetable, même dans un environnement de recherche. S'il vous plaît!
Actuellement, je suis en train de jouer avec un tel "code jetable", à savoir un projet d'explosion. La chose est que cela a commencé comme une aire de jeux, mais il est alors arrivé de devenir un peu fructueux, c'est maintenant un outil soigné avec de nombreux concepts mis en œuvre, mais le code est pratiquement systématique. Mais ce n'est pas le point principal.
Le point principal est que vous recherchez des ingénieurs pour bénéficier ultérieur de vos conclusions. Ayant fait un bon travail scientifique sur le concept général et écrire un outil qui a permis de réussir, vous pouvez facilement oublier que vous ne le faites pas pour la publication et le doctorat uniquement. Vous le faites au profit de l'humanité. Votre code peut contenir un groupe de "cas spéciaux", qui étaient difficiles à déboguer, un ensemble de bizarreries et de hacks qui ne correspondent à aucun article de conférence. Il est particulièrement important de documenter et de commenter de telles choses tout au long de votre code.
Si un développeur a décidé de mettre en œuvre vos concepts dans un produit commercial, il aurait pu étudier les bijoux et les hacks de votre code et que la mise en œuvre aurait dix fois moins de bugs qu'il aurait pu. Tout le monde dit "WOW, ses recherches sur un vraiment utile!" Mais si vous écrivez "jetais", ils disent "son concept a l'air bien sur papier, mais x essayé de la mettre en œuvre et de se noyer dans un tas de bugs".
( Modifier : extrait des commentaires ci-dessous) Pour aider les futurs développeurs de votre codeBase, vous n'avez pas besoin de beaucoup. Tout d'abord, comment chaque fonction fait . Deuxièmement, Assurez-vous que chaque solution non évidente d'un bug délicat est placée dans une validation distincte dans le système de contrôle de révision (avec un commentaire approprié, bien sûr). C'est assez assez. Et si vous faites même des choses modulaires (même s'ils ne sont pas prêts pour une réutilisation directe - c'est trois fois plus coûteux, selon Brooks), vous serez adoré par des ingénieurs qui mettront en œuvre vos recherches.
Je pense que le monde serait un meilleur endroit si les chercheurs ont jeté leur hubris et ont cessé de penser que ce ne sont pas ces codeurs sales qui font un travail menial d'écrire un bon code. Écrire un bon code n'est pas simplement un travail pour ces programmeurs stupides. C'est une chose vraiment précieuse que tout le monde devrait s'efforcer. Sans cela, votre sol expérimental, votre code, votre cervelle va juste mourir.
@Pavel a été bouleversé. J'espagie avec vos commentaires. Mais je défendrai le concept de code jetable - celui dont je parle provenait d'un projet d'alignement de la séquence basé sur le livre de Kruskal que je fixais des étudiants il y a 20 ans - je pense à BBC Basic - il a migré de cette TOC, puis C ++ Et puis à Java et maintenant je l'utilise pour l'alignement de texte. À aucun stade, c'était jamais autre chose qu'un exercice d'apprentissage et une aire de jeux. Donc, je ne possède aucune responsabilité morale de son évolution et de son état. Mais maintenant, je pense que cela a une valeur ajoutée dans un domaine différéht et je le refactore donc.
@Peter: noone vous oblige à être responsable. Ecrire un bon code est une bonne habitude et cela ne nécessite vraiment pas beaucoup de temps pour la mettre en pratique! Minuscules Descriptions de ce que les fonctions font, commentaires sur le système de contrôle de la révision du module qui me montre pourquoi une ligne particulière existe ( svn blâme ). Cela permettra à des gens de réutiliser votre travail et vous donnera donc un crédit et une attribution.
@Pavel. Merci. C'est parce que Je souhaite me comporter de manière responsable que je soumette cette question. FWIW Lorsque le code d'origine a été écrit, SVN n'existait pas :-) et le système de CVS primitifs que nous n'avions pas n'a été maintenu.
@Peter: Eh bien, vous avez eu mon point. Commentaire Que fait chaque fonction. Et assurez-vous que chaque ligne non évidente (résultant d'une solution d'un bug délicat) a un commentaire approprié et est placé dans une commission distincte. Je peux vous assurer - c'est suffisant que vous soyez loué par les adeptes. Et si vous faites même des choses modulaires (même s'ils ne sont pas prêts pour une réutilisation directe - c'est trois fois plus coûteux, selon Brooks), vous serez adoré par des ingénieurs.
[Répondre à sa propre question] Il y a plusieurs autres aspects au problème qui n'ont pas été soulevés et que j'aurais trouvé utile lors de la revise. Certaines d'entre elles peuvent être «évidentes» mais rappelez-vous que ce code était pré-svn et IDes.
dynamicaligner ) mais d'autres sont opaques ( MAINLOX , nommé car il étendit une boîte de swing). Il existe quatre programmes Main () et il y a en fait environ 3 sous-projets dans la distribution. Il est donc essentiel d'avoir un manifeste externe quant à ce que les composants étaient réellement.
-
instructions sur la façon de l'exécuter . Lors de l'exécution du programme, Main () Offrira une brève utilisation de commandes (E.G. dynamicaligner File2 File2 ) Mais cela ne dit pas ce que le contenu des fichiers ressemblait réellement. Je le savais à l'époque, bien sûr, mais pas maintenant. Donc, il devrait être associé à des fichiers dans les répertoires de frères et soeurs. Celles-ci sont plus utiles que d'essayer de documenter les formats de fichiers.
-
fonctionne toujours? . Il devrait être possible de courir chaque exemple sans réfléchir. La première question sera de savoir si les bibliothèques associées, les roulements, etc. sont toujours pertinentes et disponibles. Un ex-collègue a écrit un système qui fonctionne uniquement avec une version particulière de Python. La seule réponse est de réécrire. Donc, nous devrions certainement éviter tout verrouillage dans la mesure du possible, et je me suis formé (bien que pas nécessairement des collègues) de faire cela.
Alors, comment puis-je et vos collègues évitent des problèmes à l'avenir? Je pense que la première étape est qu'il devrait y avoir une discipline de créer un «projet» (aussi petit) lorsque vous créez du code et que ces projets devraient être sous la version de la version. Cela peut sembler évident à certains d'entre vous, mais dans certains environnements (universitaire, domestique), il existe une surcharge importante pour créer un système de gestion de projet. Je soupçonne que la majorité du code académique n'est pas sous une version de la version.
Il y a ensuite la question de savoir comment les projets doivent être organisés. Ils ne peuvent pas être sur Sourceforge par défaut car le code est (a) trivial et (b) non ouvert par défaut. Nous avons besoin d'un serveur où il peut être à la fois des projets communaux et des privés. Je calculerais que les efforts de la configuration de cela et de gérer sont environ 0,1 ETP - c'est 20 jours par an de toutes les parties (installation, formation, maintenance) - S'il existe des options plus faciles que j'aimerais savoir car c'est un grand Dépense Dans certains cas - Dois-je passer mon temps à mettre en place un serveur ou que je rédige des papiers?
Le projet devrait essayer d'encourager une bonne discipline. C'est vraiment ce que j'espérais obtenir de cette question. Il pourrait inclure:
- Un modèle de composants requis (manifeste, réveil, journal des engagements, exemples, bibliothèques requis, etc. Tous les projets ne peuvent pas exécuter sous Maven - E.G. Fortran).
- Un moyen de rechercher un grand nombre (centaines au moins) de petits projets pour les chaînes mnémoniques (j'ai aimé l'idée de déversements du code dans GoogleCs, ce qui peut être une avenue fructueuse - mais c'est un effort de maintenance supplémentaire).
- Clear Naming Conventions. Celles-ci sont plus utiles que des commentaires. J'ai maintenant régulièrement des noms du type itétryoverallxanddoy. J'essaie d'utiliser Createx () plutôt que GetX () lorsque la routine crée en réalité des informations. J'ai une mauvaise habitude d'appeler le processus de routines () plutôt que de ConverallBtoy ().
Je suis au courant mais je n'ai pas utilisé Git et Mercurial et GoogleCode. Je ne sais pas combien d'efforts sont des efforts à mettre en place et combien de mes préoccupations ils répondent. Je serais ravi s'il y avait un plugin IDE qui a contribué à créer un meilleur code (par exemple "" mauvais choix de nom de méthode ").
Et quelles que soient les approches qu'ils ont à venir naturellement aux personnes qui ne sont pas naturellement de la discipline de code et de valoir l'effort.
Peter, je suis tout à fait d'accord avec votre suggestion sur la convention de dénomination. IMHO Clear Names sont de loin les plus efficaces de communiquer votre intention via le code. Nous avons une ligne directrice: prenez au moins deux fois le temps que vous vouliez initialement penser à un bon nom.
Git ou Mercurial peut aider à la découverte et à l'effort d'entretien des préoccupations, au moins quelque peu. Si vous avez une idée d'une chaîne qui identifierait quelque chose que vous recherchez, les opérations de Git's 'Grep' et «Pickaxe» peuvent être utiles. En ce qui concerne le maintien d'un référentiel, si vous pouvez déplacer des fichiers (par quelque moyen que ce soit), vous pouvez distribuer le code de tout son historique.
De plus, vous devriez vraiment simplement modifier cela dans la question, car il clarifie plutôt que de répondre à ce que vous avez mal au dessus.
Vous pouvez également emprunter l'idée d'essais unitaires auprès des personnes TDD (développement axé sur les tests). Vous devez vous assurer que le code jetaway fonctionne de toute façon ok quand même, alors pourquoi ne pas exprimer le chèque Linke un petit test d'unité? Cela aurait deux avantages:
lire le code de test communique l'intention de la jetaresse assez clairement: après tout, il exprime ses attentes dans la même langue: Code.
Cela aiderait également au 4ème problème de votre réponse de soi: "Est-ce que ça marche toujours?". Eh bien, c'est facile: il suffit d'exécuter les tests de l'unité et ils vous disent quoi et où (et avec un peu de chance) pourquoi (it) ne fonctionne pas.
Merci. J'utilise des tests d'unité à cette fin. Ce type de test est normalement «a-t-il jusqu'à la fin sans collision». Il est très difficile de vérifier cela - dire - une sortie complexe avec des chiffres de points flottants est toujours correct.
@ Peter.Murray.Rust: Vous pouvez le vérifier avec des arguments muettes: par exemple. La plupart des équations différentielles ont une sortie connue lorsqu'il est nourri 0 pour tous les arguments. Assurez-vous que le code fait au moins cela correctement. Modulariser suffisamment, et vous pouvez avoir des tests de base sur la plupart du code.
J'ai probablement manqué le point de toute cette discussion, je le fais souvent, mais voici, une invitation pour les brickbats et la descendant ...
Si c'est un code jetable, jetez-le!
Si vous ne voulez pas le jeter, suivez le bon conseil ci-dessus. Pour moi, et j'écris une juste quantité de code jetable, la question de savoir s'il est jeté ou mis dans un état réutilisable et tenu contre une journée de pluie se résume à l'économie.
Puis-je prévoir des circonstances dans lesquelles ce code sera utile à nouveau? Une fois dans une lune bleue, deux fois par an, chaque mois?
Est-ce que je serai en mesure de réécrire ce code en moins de temps qu'il ne faut pour le rendre réutilisable? Si la réponse à cette question est non, alors combien de fois devrai-je le réutiliser pour la faire valoir en l'améliorant maintenant? (Retour à la question précédente.)
Si je fais que ce code réutilisable, vais-je pouvoir le retrouver quand je le veux ensuite? (Toute personne a déjà eu l'expérience de savoir, avec une certitude absolue, que quelque part dans votre référentiel de code, il n'y a que le fragment que vous voulez, mais que vous n'ayez pas indifférent ce qu'on appelle, ni où regarder ni grep?)
Enfin, l'approche en 3 étapes pour faire du code rapidement écrit réutilisable. Arrêtez-vous après ces étapes que vous aimez:
1) Documez le code comme une boîte noire. Entrées, sorties, exploitation (s). Déposer ce document avec soin.
2) Écrivez des instructions sur la manière de construire / interpréter / installer le code, au cas où vous auriez jamais à le porter. Déposer ces instructions soigneusement.
3) Seulement si cela vaut l'effort - améliorer la qualité du code source pour rendre le code à l'avenir à l'avenir. Assurez-vous que les sources sont dans le système de contrôle source et trouvable.
considère
marque
Tout à fait raison, quand il s'agit là-bas, il existe une distinction entre le code jetable et l'inachevé. La jetaresse par définition n'est pas suffisamment complexe à vouloir ou à conserver, alors peut facilement être ré-généré dans une époque plus éclairée. Le code adressé est un coup de tequila bon marché. Code inachevé, d'autre part, a vraiment besoin de bons soins: Enroulement de la laine de coton (commentée), conservée à une température de const dans un endroit sombre, tourna à intervalles réguliers et avoir «maîtriser les expressions régulières» en une voix douce A l'heure de se coucher.