Comment puis-je rendre mon code plus facile pour la prochaine développeur à comprendre?

Question

J'ai été à mon premier travail de programmation pour environ 8 mois maintenant, et j'ai appris une quantité incroyable jusqu'à présent.

Malheureusement, je suis le seul développeur pour une petite entreprise de démarrage pour les applications internes.

Pour la première fois, cependant, je vais passer une partie de mes projets à quelqu'un d'autre quand j'ai quitter ce travail. J'ai documenté tous mes projets à fond (du moins je le pense), mais je me sens toujours nerveux au sujet de quelqu'un d'autre à la lecture de mon code.

Par exemple, j'ai toujours fait ce genre de chose.

for (int i = 0; i < blah.length; i++)
{
//Do stuff
}

Dois-je le nom de " i " quelque chose de descriptif? C'est seulement une variable temporaire, et ne peuvent exister à l'intérieur de cette boucle, et il semble qu'il est assez évident que la boucle ne avec "je".

Ce n'est qu'un exemple. Un autre est que j'ai le nom des variables de la même façon... je n'ai pas vraiment conforme à une norme de nommage en dehors de départ de tous les membres avec un trait de soulignement.

Existe-il des ressources qui pourraient me montrer comment le rendre plus facile pour le prochain développeur? Existe-il des normes pour ce type de chose?

Answer 1

Le Code Complet de Steve McConnell est un bon endroit pour commencer à chercher les réponses à vos questions et un ensemble beaucoup plus que vous n'avez pas encore posée, mais bientôt.

Answer 2

Si vous avez le suivant fait, il ira un long chemin à soulager vos remplacement de la douleur:

1. Produire un document d'architecture montrant la structure globale de votre logiciel et les parties interagissent.
2. Document à chaque membre de la variable / fonction / classe pour indiquer ce qu'ils font (pas comment ils font).
3. D'écrire et de documenter un certain nombre de tests qui montrent la façon dont le programme fonctionne et à quoi vous attendre dans les moyens, vous vous attendez à être utilisé. Assurez-vous que toutes les données de l'exemple est enregistrée afin que votre remplacement peut ré-exécuter les tests d'acquérir une compréhension de la façon dont il devrait fonctionner.
4. Assurez-vous que votre code suit une norme. Même si c'est pas un classique, le code qui est au moins consisten avec lui-même, sera plus facile à suivre.
5. Si vous êtes à l'aise avec elle, laissez certains détails de contact de sorte que le gars ou la fille qui prend le relais peut au moins e-mail ou de vous donner un appel si ils sont vraiment coincé. J'ai fait cela pour divers projets / travaux. Il ne faut pas longtemps pour répondre à l'étrange question, mais elle peut facilement enregistrer le verser de l'âme qui est hérité yuor codebase beaucoup de temps.

Si vous voulez une norme de codage à respecter, il y a un associé post ici sur DONC qui a des suggestions.

Answer 3

Outre le point de "travail effectif" (--les 3 réponses sont plutôt bien--) gardez à l'esprit que nous (les programmeurs) sont un arrogant (et à peu près ignorant) de cinglés;

N'importe comment dur vous essayez d'écrire de bonnes (et bien documenté) du code ou de la quantité de sucre syntaxique vous feriez appliquer: pour le nouveau gars que votre code sera toujours "sucer" (au moins à un certain degré), car il n'a pas l'écrire.

Pour votre exemple (à l'aide de je pour la boucle), c'est seulement un local de la variable de boucle. Je ne voudrais pas être trop dur sur vous-même. Tant que le code est assez beaucoup d'auto-explique à lui de gérer.

Answer 4

Parmi les variables i est considérée comme l'une particulière de nommage cas. Avec j, k et l, i est bien entendu être provisoire "à l'encontre" de la variable pour une utilisation dans des boucles. Tant que votre utilisation soit conforme, ce ne sera pas un problème.

Voici quelques règles à suivre pour rendre votre code plus facile à comprendre:

• Être cohérent: assurez-vous que votre variable conventions de nommage et de la conception est cohérente. Si vous créez souvent des variables temporaires pour les boucles, ils sont toujours appelés i? Utilisez-vous i n'importe où ailleurs pour signifier quelque chose de différent? La cohérence signifie qu'il y a des schémas de la logique de votre code. Les modèles sont faciles à prendre et à suivre.
• Expliquez-vous: assurez-vous que les commentaires expliquent pourquoi vous faites quelque chose, pas ce que vous faites. Des commentaires comme // Loop over array n'aident pas; n'importe qui peut lire votre code et de voir que vous êtes la réalisation d'une boucle. Ce qu'ils veulent savoir, c'est pourquoi vous le faites.
• Document de cours: Donner à quelqu'un de la documentation sur l'objet de chaque classe, interface, membre de la propriété, même si c'est juste une seule ligne d'explication, c'est d'une grande aide lorsque vous essayez de comprendre ce que les composants d'une application ne. Si vous mettez des commentaires XML dans Visual Studio, il va générer un message d'avertissement à chaque fois que vous oubliez d'ajouter que le strict minimum un résumé de chaque membre. Ces commentaires ont également l'avantage supplémentaire de la prise en charge intellisense, ce qui rend votre code plus facile de travailler avec.

Si vous pouvez dire que votre code suivant ces lignes directrices, je serais heureux d'hériter de votre code. Franchement, je l'ai encore donné un code qui suivie, même l'un de ces conseils, mais j'écris mon propre code dans une tentative de faire thenextguy du travail beaucoup plus facile.

Answer 5

Il y a 2 outils que je connais qui peut vous aider beaucoup. StyleCop et FxCop. Suivez les liens pour avoir une idée de ce que ces outils sont tout au sujet. Le gros avantage de ces outils est que vous n'aurez pas à passer par le biais de votre code manuellement, ce qui serait sans aucun doute prendre un temps très long.