Normes du code

Retour aux meilleures pratiques

Meilleures pratiques pour le contrôle du code source, les messages de validation, la documentation et la gestion de projet

Contrôle de source Github

Tout le code doit être conservé sur GitHub. Assurez-vous de livrer et de pousser régulièrement. La meilleure pratique est de livrer plusieurs fois par jour lorsque l’on code activement et de pousser AU MOINS une fois par jour. La fin de la journée de travail est un moment idéal pour pousser. Cela sert trois objectifs importants :

  1. Cela nous évite de perdre la trace de notre code si nous écrasons un fichier ou si nous voulons revenir à une version plus ancienne d’un script. Chaque version de notre code qui a été validée et poussée peut être récupérée en cas de perte ou d’écrasement. Le code qui n’a pas été validé et poussé ne peut pas être récupéré.
  2. Le partage de notre code nous permet d’apprendre les uns des autres et de réutiliser le code développé par d’autres membres de l’équipe. Si votre référentiel est privé, votre code n’est visible que par les personnes avec lesquelles vous l’avez explicitement partagé.
  3. C’est très utile pour le dépannage ! Lorsque votre code est en ligne, il est beaucoup plus facile pour les autres membres de l’équipe de comprendre le problème que vous rencontrez, car ils peuvent voir l’ensemble de votre dépôt, y compris le script qui pose problème. Le contrôle de version GitHub affichera la version la plus récente et permettra d’explorer toutes les modifications apportées au script.

Git peut être délicat et nous avons tous eu à faire face à des problèmes liés à Git. N’hésitez pas à demander de l’aide sur Slack (#help) ou à chercher sur le web car il existe de nombreuses ressources, comme ce tutoriel de GitHub. Vous finirez par apprendre et nous avons beaucoup d’expertise dans notre équipe pour vous faciliter la vie. Beaucoup d’entre nous utilisent Sourcetree ou GitHub Desktop pour gérer leurs dépôts.

Messages et descriptions des livraisons

Lorsque vous effectuez un commit Git, incluez un message court mais significatif qui décrit les changements que vous effectuez. Les changements typiques incluent de nouvelles fonctionnalités, un code amélioré, des paramètres mis à jour, des corrections de bogues et des corrections parmi d’autres. Le message de validation doit fournir des informations sur le type et la raison des modifications apportées (par exemple, quelles modifications avez-vous apportées depuis la dernière validation ?) et pourquoi (par exemple, s’agit-il de corriger un problème, d’ajouter une nouvelle fonctionnalité, etc.) Ces messages de livraison peuvent être courts et précis, mais ils devraient vous être utiles, ainsi qu’aux autres personnes qui pourraient consulter le référentiel à l’avenir. Une utilisation plus avancée permet d’écrire des messages de demande d’extraction lorsque l’on travaille à partir d’un développeur et d’un dépôt maître propre, et vous pouvez en savoir plus à ce sujet une fois que vous êtes familiarisé avec les bases de Git

Gérer votre projet

Il est important de prendre des notes détaillées sur votre projet, y compris sur la conception, l’avancement et les analyses. Les notes doivent être aussi complètes que possible afin que vous puissiez garder une trace des méthodes, des changements effectués, etc. En incluant tous ces détails, vous serez mieux équipé pour avancer plutôt que de tourner en rond et pour finalement publier vos résultats. Quelques points clés :

  • Il n’est jamais trop tôt pour commencer à rédiger vos notes de projet ! Vous devriez les commencer dès que vous débutez un projet, afin d’avoir des détails sur l’ensemble du processus.
    • Il existe de nombreuses plateformes différentes que vous pouvez utiliser pour prendre vos notes de projet, en fonction de vos préférences. Les membres de l’équipe utilisent souvent Word ou Rmarkdown, mais il existe d’autres applications de prise de notes tout aussi efficaces. Il est préférable de prendre des notes en ligne car elles sont à la fois consultables et partageables.
  • Des modèles et des exemples de notes de projet sont disponibles :
  • Restez organisé et gardez une trace de votre flux de travail. Vous devez inclure toutes les informations nécessaires à la rédaction des sections “méthodes” et “résultats” d’un article, tout en gardant une trace des changements progressifs en cours de route.
    • Notez ce que vous avez fait, ce que vous avez vu lorsque vous avez apporté des modifications à votre projet. Notez bien tout ce que vous essayez, car vous ferez beaucoup d’essais et vous ne vous souviendrez pas de tout ce que vous avez fait.
    • Il peut être utile d’inclure tous les détails de vos simulations à chaque mise à jour (par exemple, la simulation a duré X années avec X détails d’intervention, etc. Ces notes d’avancement détaillées vous aideront à éviter de répéter inutilement les mêmes étapes.
    • Assurez-vous d’inclure des parcelles et des notes de discussion au fur et à mesure, car elles vous aideront à comprendre les résultats de ce que vous avez fait et vos réflexions à ce sujet.
      • Les outils utiles comprennent snippingtool ou Greenshot pour faire des captures d’écran des tracés et des messages d’erreur, et écrire des messages slack pour vous-même ou avoir un autre endroit pour des rappels rapides, des extraits de code, ou des notes.
  • Vos notes de projet doivent être accessibles à toute personne avec laquelle vous collaborez régulièrement. Pour l’enrichissement de la faculté, assurez-vous de partager vos notes avec Jaline, votre binôme, et le reste du personnel enseignant. Nous verrons cela ensemble lors de la session de mise en place du projet.