Je n'appellerais pas cela éthique / contraire à l'éthique mais plutôt professionnel / non professionnel.

Votre deuxième note est celle que je choisirais car elle n'inclut aucune opinion et fournit les informations pertinentes au prochain développeur.

La première note me semble plus un coup de gueule qu'un commentaire utile.

En règle générale, j'essaie de fournir au moins un pointeur lors de l'écriture de code qui présente un risque ou qui est un hack pour contourner tout problème externe; cependant, c'est quelque chose que j'ai trouvé utile pour moi-même et l'est encore plus pour quelqu'un qui n'a pas développé ce code (laid).

Soyez constructif.

Commentez des choses comme les bogues et les problèmes, car ils aident à la fois le projet et un nouveau développeur, mais évitez les commentaires comme "Désolé si vous avez besoin de maintenir cela", cela n'a pas d'intérêt en eux.

Le premier lit un IMO peu professionnel, et oserais-je le dire un peu pétulant avec les références à "contre mon meilleur jugement". Si je voyais cela en tant que responsable du développeur, je ne regarderais pas trop gentiment dessus.

Le second se lit beaucoup mieux, il est professionnel, succinct et fait passer les informations clés pour aider tout futur responsable le code. Ce serait un bon commentaire à mon avis.

Est-il éthique / professionnel de laisser des commentaires sur le code concerné

Professionnel et obligatoire: celui (s) qui y travaille aura besoin de commentaires pour gagner du temps / de l'argent / maux de tête

expliquer vos pensées / raisonnement qui peuvent être partiellement basés sur des opinions?

Évitez cela. Tenez-vous en aux faits, gardez l'approche professionnelle et soyez constructif, comme également mentionné par @ Voyant. .

Commentez la partie technique de la bug, expliquez si nécessaire, utilisez une liste TODO, recommandez quelque chose d'utile tant que c'est professionnel et lié à votre travail / code.

Note du développeur: Ce processus est susceptible de casser si les volumes de données augmentent. Le journal des erreurs peut être trouvé [ICI] pour alerter si le processus s'exécute trop longtemps. À l'avenir, il pourrait être utile de ('Il était prévu de' / 'cela pourrait être utile de'): a) vérifier AAA b) modifier BBB c) tester CCC

Aucun responsable ou patron n'aimerait voir des critiques non constructives et basées sur des opinions.

• Non

  • dire que c'est faux
  • pleurer
  • se plaindre
  • écrire des commentaires non techniques basés sur des opinions (*)

• Préférez pour:

  • ajouter une liste de tâches
  • signaler des faits
  • donner des informations
  • être utile aux autres membres de l'équipe même si vous n'en faites plus partie

/ * (*) MODIFIER : 30/06/2017: ajout de "non technique" à la liste Ne pas pour la rendre plus claire, basée sur @ Wildcard commentaire. * /

Chaque fois que je me suis retrouvé dans la situation de reprendre quelque chose, d'être laissé seul avec des documents et des commentaires sur le code de production et que je n'avais personne à qui parler,

J'aurais aimé trouver des conseils basés sur des opinions . Mais tout ce que je trouve généralement est:

  // TODO !!!!  

Donc je dirais, documentez-le aussi techniquement et précisément que possible , mais avant de laisser de côté une information importante , votre remplaçant vous pardonnera d'être basé sur l'opinion au lieu d'écrire simplement un autre "Je n'ai pas fini ce" -comment aka / * TODO !!!! * / .

Eh bien, au moins je le ferais.

Puisque vous demandez "Comment cette situation pourrait-elle être gérée autrement?", je vais sortir un peu des sentiers battus et dire

Utilisez un outil de suivi des bogues - et si vous pensez même sur l'utilisation des commentaires de code, jetez un long regard critique sur vos pratiques de codage.

Sérieusement. Si vous pensez qu'il y a des bogues dans votre code, vous rédigez un rapport de bogue. Vous utilisez l'un des nombreux systèmes de suivi des problèmes (par exemple Bugzilla) qui sont disponibles gratuitement et faciles à utiliser et à entretenir. Enfer, utilisez une feuille de calcul Excel si vous le souhaitez. Les rapports de bogue peuvent être aussi détaillés ou spéculatifs que vous le souhaitez. Ils peuvent (et devraient!) Inclure des justifications expliquant pourquoi la direction a pu décider de ne pas les corriger. Ce sont toutes les meilleures pratiques pour le développement de logiciels.

Si je prends votre code pour le maintenir, je chercherai ce traqueur de bogues. Il y a de bonnes chances que je fasse de la maintenance car il y a un bogue qui doit être corrigé. Je vais donc supposer que nous avons une liste de bogues, et qu'elle est raisonnablement complète.

Si je trouve qu'il n'y a pas de traqueur de bogues, je serai inquiet. Pire que cela, si je trouve que le code est jonché de commentaires disant "c'est susceptible de casser", je vais maudire votre nom. Le seul moyen que j'aurai pour trouver les bogues que nous pourrions avoir dans le système est de parcourir chaque fichier, ligne par ligne, car je n'ai aucune idée des autres mines terrestres que vous avez laissées aux responsables de la maintenance.

Alors faites le travail correctement. Mettez vos rapports de bogues dans le suivi des bogues. Rendez-les aussi détaillés que vous le souhaitez. Incluez les noms des responsables qui ont pris la décision de ne pas corriger les bogues - ce sera une information vitale pour un futur responsable pour trouver la bonne personne à qui parler. Si vous voulez ajouter des commentaires dans votre code disant "Cela a un problème connu - voir CR1234 pour plus de détails" alors vous allez au-delà.

Mais vraiment pas envisager les commentaires de code seuls comme moyen approprié de signaler les bogues pour les responsables. Ils ne le sont pas.

En tant que personne prenant en charge le code, comprendre pourquoi il a été écrit est très utile. Je préfère de beaucoup avoir cette information en commentaire (au lieu d'un document qui ne me sera peut-être pas donné) que de ne pas l'avoir, quel que soit le manque de professionnalisme de la direction.

Mais c'est la direction qui écrira votre prochaine référence et non la personne qui reprend le code. Donc, si vous n'êtes pas en mesure de fournir les informations d'une manière qui semble professionnelle, il vaut peut-être mieux ne pas les fournir du tout et laisser le prochain programmeur découvrir l'erreur qu'il a commise en acceptant le travail.

Il y a des années, j'ai dû apporter des modifications à un programme que quelqu'un d'autre avait écrit, et je suis tombé sur un gros bloc de commentaires au milieu du code qui commençait: "C'est un triste commentaire sur l'Amérique moderne quand une personne est forcée pour continuer à travailler sur un projet qui ne l'intéresse pas », et a continué sans arrêt sur la façon dont cette personne détestait son travail. Puis il a mis fin au commentaire et est retourné au brassage des données. Je l'ai mentionné à l'un des autres programmeurs et elle a dit que ce type mettait toujours ces diatribes dans son code. C'était plutôt amusant, mais cela lui donnait l'air plutôt idiot.

Comme d'autres l'ont noté, un commentaire comme le vôtre est raisonnablement objectif et très probablement utile à un futur programmeur.

J'inclus régulièrement des commentaires dans le code qui décrivent les limitations. "Cette fonction est lente mais elle n'est pas appelée très souvent donc cela n'a pas vraiment d'importance", "Cette validation ne fonctionne que pour les adresses américaines - elle devra être modifiée si jamais nous gérons des adresses étrangères", etc.

En général, je pense qu'il est bon et raisonnable d'écrire des commentaires qui disent franchement, "voici les limites de la façon dont nous avons fait cela, mais nous avons choisi cette approche parce que ..." Un futur programmeur a alors un indice et n'a pas à le comprendre à nouveau. Je suis sûr que quiconque travaille depuis assez longtemps dans le secteur a eu des moments où il a dit: "Wow, cela a été vraiment mal fait, je vais le réécrire de cette façon", puis nous passons des heures (ou mois) lors de la réécriture, seulement à un moment donné pour découvrir: "Oh, ça ne marche pas. Maintenant je sais pourquoi le programmeur original l'a fait comme il l'a fait."

inclure des gémissements ou des diatribes dans les commentaires, "j'ai été obligé de le faire de cette manière stupide parce que le patron est un crétin" ou autre. Pour la même raison que je ne dirais pas ça à un collègue. Ou pire, écrivez un e-mail disant cela. Même si j'arrête avant qu'il ne soit découvert pour ne pas être renvoyé, c'est toujours impoli et inutile.

J'inclus occasionnellement des remarques pleines d'esprit (ou du moins des tentatives). Je pense que ce genre de chose est bon pour le moral, mais il peut certainement être exagéré.

Je suis dans le même bateau - peut-être avec un peu moins de temps avant de partir que vous.

La solution convenue dans notre cas (une bonne, je pense) était:

• Accomplissez votre tâche de manière professionnelle, dans la mesure du possible (dans votre exemple, prenez la deuxième option).
• Dans le cadre de votre transfert, préparez un document avec les sources les plus probables / attendues des problèmes / points d'arrêt.
• Dans ce document, vous pouvez poser quels sont les problèmes actuels de l'architecture logicielle, en fournissant vos points de vue - et même suggérer des moyens possibles de les résoudre.

De cette façon, vous gardez la source principale de votre travail aussi professionnelle que possible, et vous donnez également votre évaluation honnête aux futurs propriétaires du produit.

J'ai vu des commentaires qui auraient eu des implications juridiques s'ils avaient été découverts au tribunal. Il y a donc une raison pour laquelle les commentaires du type "Je sais que cela pourrait échouer de manière catastrophique, mais je le fais quand même" devraient être évités .

Nous avons tous été dans cette position où il nous est ordonné de couper les coins ronds contre notre meilleur jugement afin de respecter une date limite ou une autre étape, mais vous devenez une responsabilité pour l'entreprise si vous travaillez autour de l'édition cette information (plus que de simplement le faire et de la réparer tranquillement plus tard) parce que vous annulez toute réclamation future de déni plausible.

Quant à la question du professionnalisme, quand un certain code source populaire d'un logiciel était fuite il y a quelques années, les gens ont eu une journée sur le terrain sur certains des commentaires que les développeurs ont répandus dans le code. C'était embarrassant pour l'entreprise, qui a depuis mis en œuvre la révision des commentaires - un panel trop zélé rejette désormais les commits de code contenant des commentaires potentiellement offensants ou non professionnels.

En tant que développeur de logiciels moi-même ...

Oui, c'est merveilleux si le code a (le bon type de) commentaires et variables / fonction / méthode / objet / ... noms qui parlent réellement pour eux-mêmes ... et je préférerais des informations détaillées sur pourquoi et pourquoi pas:

Il y a une limite stricte sur le volume de données qui peuvent être traitées ici, car nous itérons sur toute la base de données et récupérez chaque ligne. Les tampons de restauration ont déjà été définis aussi grands que possible par les administrateurs sur DB1 et DB2, mais à un trafic typique (à partir de juin 2017) qui ne nous donne que 2 heures à la période la plus calme entre 03h00 et 05h00, et (à partir de juin 2017) une exécution prend 1h40 (+/- 3 minutes).

En comparant les boutiques, il s'agit d'une limite de lecture et d'envoi de données logicielles et matérielles de la base de données, ainsi que de traitement parallèle et le partitionnement est déjà appliqué dans la mesure du possible sans risquer des données incohérentes.

En raison de la logique métier, des contraintes de produit et de matériel, en particulier A, B et C, il n'est pas possible d'utiliser des tables temporaires, celles-ci et D et E nous empêchent également de simplement vider ou exporter en masse la base de données. Une autre option envisagée consistait à répliquer la base de données sur DB_r, en supprimant la réplication de DB_r et en y travaillant. Malheureusement, revenir à une réplication à jour génère trop de charge sur DB1 et DB2 pour être viable, et cela s'aggrave avec le volume de données toujours croissant.

Un e-mail automatisé est envoyé pour développer @company et admin @ company (avec un pointeur vers cette partie de code) si le temps d'exécution dépasse 1:45 et un autre pour 1:55; il sera également enregistré par syslog comme grave / critique. (Les adresses e-mail sont définies dans /blah/blubb/const.h, vous pouvez ajouter votre adresse e-mail au cas où vous ne seriez pas sur la liste pour une raison quelconque.)

La direction a été informée que ce sera un problème dans un proche avenir, mais ils peuvent avoir besoin d'un rappel que le futur proche est devenu maintenant. Les solutions possibles sont:

• Changez le RAID de la base de données du disque dur en SSD et obtenez plus de RAM et plus de cœurs vers les serveurs de base de données --- rapide mais coûteux (également les licences de logiciel DB)
• Passez à XXX DB ou YYY DB, qui permet une exportation raisonnable à partir d'une base de données en cours d'exécution, mais ne dispose pas des fonctionnalités X et Z, de sorte que le code doit être adapté à cela --- ce qui coûtera beaucoup d'argent pour le logiciel et le temps de changer et de vérifier le code
• Le déplacement d'anciennes données vers une base de données «archive» ou «entrepôt de données» réduirait la quantité de données sur DB1 et DB2 d'au moins 50%, peut-être 80%, ce qui résoudrait ou au moins reporterait le problème d'un certain nombre des années --- Les ventes doivent être convaincues que gérer leurs statistiques avec des données datant de moins d'un jour est en fait viable, ce qui a toujours été difficile. Cela signifie également qu'un nouveau matériel est nécessaire.

De plus, tout ce qui précède entraînera très probablement un jour ou deux d'indisponibilité, car la réplication ou la copie de la base de données entraînera la création d'au moins un serveur de base de données. très insensible, et cela bouleversera tout le monde, du conseil d'administration et du PDG en aval. Par conséquent, ces actions doivent être planifiées, testées et scénarisées bien avant le changement réel - un luxe que nous n'aurons pas si nous attendons beaucoup plus longtemps - et si possible devraient coïncider avec une panne planifiée (partielle ou complète).

Les tests semblent indiquer que si vous répliquez la base de données vers un DB_r et que vers un DB_r_r, vous pouvez maintenir la charge en raison de la réplication de DB1 et DB2 à un niveau bas pendant que vous transférez ce travail vers DB_r, mais faute de matériel être testé avec des quantités réalistes de données.

Cela me servira bien dans 6 mois ou un an. Cela me rappellera toutes les raisons, un indicateur à quel point c'est mauvais en ce moment, un rappel pour vérifier si certaines conditions sont toujours vraies (et si certaines le font, réexaminez si elles peuvent être modifiées maintenant), ce qui a été pensé (et pourquoi cela ne fonctionnerait pas), et quelques informations sur la dynamique sociale et de pouvoir.

Une note comme Il y a quelques bogues connus est à peu près aussi utile que "Attention aux snargels!" Et puisque la prochaine personne à maintenir ce code sera un psychopathe avec un faible pour les tronçonneuses qui connaît votre adresse actuelle ...

Tenez-vous en aux faits et au présent, et omettez tout ce qui est basé sur le contexte de ce qui a dû être fait dans le passé. Par exemple, ne dites pas:

Note du développeur: Ce processus est susceptible de s'arrêter si les volumes de données augmentent. Il aurait été préférable d'utiliser une exportation en vrac mais pas possible à l'époque. Il y a une configuration du journal des erreurs pour alerter si ce processus s'exécute trop longtemps et qu'il peut être trouvé à la place X.

Au contraire, vous pouvez utiliser quelque chose du type:

Cet algorithme devrait être remplacé par une importation groupée si le volume augmente à X entrées / prend plus d'une heure à compléter.

Il est facile pour vous de savoir d'où vous venez à partir du moment où vous avez écrit le code et bien sûr, cela reste dans votre esprit lorsque vous le regardez, mais votre prochain successeur ne commencera qu'avec l'état actuel de la base de code.

En cas de doute, commentez davantage.

Ces types de commentaires sont très utiles, car ils communiquent des informations vitales. Peu importe que cela paraisse professionnel ou pleurnichard. Ce qui compte, c'est que cela soit utile pour résoudre ou prévenir de futurs problèmes.

Chaque développeur traverse ce moment où il est bloqué sur quelque chose pendant une longue période, ou a des délais serrés et doit pirater quelque chose. Les gens comprendront, en particulier ceux qui vous ont poussé à respecter une échéance difficile.

Il est très important de noter quand un morceau de code n'est pas optimisé, voire instable et non testé. Ou même des choses que vous prévoyez d'améliorer à l'avenir mais que vous n'avez tout simplement pas le temps pour cela maintenant.

En fonction de votre modèle de projet et de votre domaine d'activité, il peut être professionnel d'écrire et même de déployer un prototype ou un code de preuve de concept. C'est ce qu'on appelle la dette technique, et comme toute dette, l'entreprise doit l'accepter au moment opportun et la rembourser au moment opportun ... avec un «paiement d'intérêts» sous forme de travail supplémentaire.

Il était de votre devoir professionnel d'expliquer le concept de l'endettement technique à vos managers, même si vous ne pouvez pas utiliser de termes techniques. Il est de leur droit et de leur devoir de décider des niveaux d'endettement acceptables, même s'ils ne comprennent pas les détails techniques. Ils sont payés pour équilibrer le risque entre p. être en retard sur le marché et augmenter les coûts de maintenance. (Les choses seraient différentes lorsque les normes de qualité sont réglementées par des autorités professionnelles ou fixées par la loi, bien sûr.)

Vous avez donc fait des choses qui étaient erronées d'un point de vue purement technique , et vous ressentez le besoin de vous excuser de votre savoir-faire auprès de votre successeur. Vous ressentez également le besoin de donner des indications pour d'éventuelles améliorations. Comme mentionné dans d'autres réponses, cette dernière est une très bonne chose.

• Expliquez les limites de votre code actuel. Vous pourriez même faire référence aux documents d'exigences. UX a écrit dans la spécification X.Y qu'une liste typique a moins de 10 entrées. Donc, le tri des bulles est parfaitement adéquat.
• Expliquez pourquoi les choses n'ont pas été faites, de manière technique . Toujours utiliser Java 1.7 car nous ne pouvons pas utiliser la bibliothèque X plus récente que la version Y.Z. et cela ne se compilera pas avec la version 1.8.

Qu'est-ce que l'éthique?

Puisque vous demandez spécifiquement si c'est éthique ou non, cela peut aider à formuler le problème en termes de différents systèmes éthiques. C'est un sujet controversé et je ne suis en aucun cas un expert, juste un homme opiniâtre essayant d'aider (et qui a vraiment apprécié son cours d'éthique à l'université), alors gardez cela à l'esprit.

Notez également que ces différents systèmes s'entendent rarement sur ce que vous devez faire, c'est à vous de décider lequel est le plus pertinent. Il y en a beaucoup, beaucoup que je n'inclus pas ici.

L'éthique postmoderne soutient que les affaires humaines sont une chose désordonnée pour laquelle aucun système unique ne fournit une réponse complète. Nous pouvons donc travailler à partir d'un système comme base pour résoudre la majorité des problèmes, puis en incorporer d'autres pour traiter les problèmes périphériques.

L'éthique des affaires

Il me semble que vous l'êtes le plus préoccupé par le fait que votre propre code d'éthique peut entrer en conflit avec l'éthique commerciale de votre entreprise. Différentes personnes ont des idées différentes sur ce que devrait être l'éthique d'une entreprise, mais nous n'avons pas besoin de prendre une tangente à ce sujet. Votre entreprise doit avoir un code d'éthique écrit, ou un code de conduite, ou quelque chose du genre. Vous pouvez le trouver, le lire et voir comment votre propre code d'éthique s'y oppose.

Mais ces documents sont généralement des directives de plus haut niveau, de la haute direction, qui découlent de leurs droits et responsabilités en tant qu'entreprise et employeur au sein du ou des pays où ils vivent. Idéalement, il fournit un État de droit sur lequel bâtir la politique, mais il peut également inclure des directives comportementales quotidiennes pour les employés. Jetez un œil.

Ethique confucéenne

Les idées de Kong Fuzi visent à renforcer la société en renforçant des rôles interpersonnels harmonieux. Il l'a fait avec succès pendant de nombreux siècles en tirant parti du pouvoir de l'émotion humaine et de l'irrationalité pour produire un effet positif. Vous avez vous-même dit qu'il n'y aura pas un tel rôle interpersonnel de mentor-étudiant. Par conséquent, le confucianisme suggère que vous devez renforcer l'harmonie de votre organisation en vous basant sur les rôles interpersonnels que vous avez, tels que collègue-collègue, employeur-employé, superviseur-supervisé.

Comment cela est fait, vous seul peut savoir. Peut-être que cela signifie simplement faire ce que vous pouvez pour rendre le lieu de travail meilleur pour tout le monde avant votre départ. Peut-être que cela signifie parler à votre superviseur de la façon dont ses attentes et vos attentes se sont déroulées pendant votre mandat, et ce que cela signifie pour le prochain. Peut-être autre chose.

Le point clé ici, cependant, est de mettre de côté votre propre ego. Actuellement, vous pensez aux problèmes que vous avez rencontrés et comment les atténuer pour votre successeur. Au sein de l'école de pensée confucéenne, cependant, cela serait considéré comme égoïste. (Oui, même si vous êtes préoccupé par une autre personne.)

Ethique utilitaire

Ce système est dans la tradition de John Stuart Mill. Il soutient que la bonne action est celle qui aboutit à la plus «utilité» - une mesure du bonheur qui n'est pas nécessairement objective ou empirique. L'objectif est d'obtenir le plus de bonheur pour le plus grand nombre.

(Hors sujet: Les céréales pour le petit-déjeuner du samedi matin ont une bande dessinée amusante sur celle-ci.)

Son application ici n'est pas si mauvaise. L'utilitarisme suggère que vous vous concentriez sur la fourniture de commentaires et de documentation qui permettront le plus efficacement à votre successeur de se mettre au courant. Ils n'ont pas besoin d'une maîtrise totale, ils ont juste besoin d'un niveau de productivité satisfaisant eux-mêmes et leur superviseur. Et votre propre utilité est prise en compte dans le décompte - si cela commence à vous rendre misérable, passez à autre chose.

L'éthique kantienne

Immanuel Kant. Grand nom de l'éthique, et son truc plonge rapidement dans l'abstrait. Le résumé rapide et sale de ses idées est que quelque chose est vraiment juste et bon seulement quand il n’est pas qualifié. Ainsi, la fin ne justifie pas les moyens, ni les moyens ne justifient la fin - chacun doit être autonome. En ce sens, la seule considération éthiquement pertinente pour décider de ses motivations. Le motif proposé par Kant était le devoir et l'obligation.

Il y a beaucoup à critiquer dans ce système, mais cela vaut la peine d'y réfléchir comme l'une des nombreuses options. Vous avez un devoir et une obligation envers votre employeur, mais pas envers votre successeur. Une partie de ce devoir peut impliquer la préparation du code source et de la documentation pour que votre successeur puisse exercer vos fonctions. Que ces matériaux soient ce que vous voulez ou ce que veut votre successeur, cela n'a pas d'importance. Même si les matériaux s'avèrent inadéquats, vous avez rempli votre devoir et, au pire, votre successeur a simplement des devoirs un peu plus onéreux à remplir.

Éthique pragmatique

Dans la tradition de John Dewey. Ce système soutient que l'éthique elle-même est un processus scientifique d'expérimentation, d'itération et de révision. En outre, il soutient que le comportement éthique n'est pas conduit par des individus mais par des sociétés. Il propose également que l'éthique soit sensible au contexte, changeant avec le temps et le lieu.

L'inconvénient est qu'elle décrit la manière dont les décisions éthiques sont prises, et pas très prescriptive sur la manière de prendre des décisions éthiques. Mais cela suggère que les décisions sur ce qui est bien et ce qui est mal (comme votre commentaire, ... contre mon meilleur jugement ... ) ne vous appartiennent plus. Le bien et le mal de ces décisions appartiennent à la société, au nom de laquelle votre entreprise prend la décision, au nom de laquelle vous prenez vous-même la décision.

Une fois que vous êtes parti, vous n'êtes plus en mesure de prendre ces décisions au nom de l'entreprise. Par conséquent, ces décisions ne sont pertinentes que dans la mesure où elles permettent à votre successeur de faire de même. S'ils pensent que votre opinion est folle, alors les commentaires d'opinion n'ont aucune valeur éthique.

Par conséquent, dans ce système, l'action éthique consiste à permettre une prise de décision éclairée par votre successeur, en mettant l'accent sur les informations empiriques, afin qu'ils soient mieux préparés à conduire la prochaine itération de décisions sur ce qui est bien et ce qui est mal.

Éthique des soins

C'est la tradition de pensée qui découle du travail de Carol Gilligan sur développement psychologique de la femme. En mettant de côté les questions féministes, elle soutient que ce qui est bon et juste dépend de la façon dont on prend soin des autres; favorise le développement; et favorise le bien-être.

De cette position, le professionnalisme n'a même pas d'importance dans ce scénario. Vous avez quelqu'un qui héritera de votre poste et vous ne serez pas là pour les aider. Le soin éthique suggère que vous devriez faire tout ce que vous pouvez, maintenant, pour leur donner la maîtrise que vous détenez maintenant sur le code source. Cela inclut les connaissances objectives qui peuvent être utilisées dans l'analyse, ainsi que les connaissances subjectives qui peuvent être utilisées dans le jugement.

Conclusion

Réponse peu claire. Lisez, réfléchissez, mélangez et comparez, jugez.

Le développeur qui maintiendra ce code (que ce soit vous-même ou une autre personne) ne tirera aucun bénéfice des remarques telles que "contre mon meilleur jugement" et "désolé si vous devez maintenir cela". Les commentaires que vous laissez derrière devraient être utiles pour l'application, c'est leur but.

D'après les deux commentaires que vous avez mentionnés, j'irais avec le second, avec un peu de modification.

Note du développeur: Ce processus est susceptible de s'arrêter si les volumes de données augmentent.

Avez-vous identifié la cause / le point exact de la rupture? Ajoutez-le.

Il aurait été préférable d'utiliser une exportation groupée mais pas possible pour le moment.

"Il aurait été préférable »est au mieux subjectif. Mentionnez simplement qu'une exportation en masse pourrait potentiellement aider à résoudre / atténuer le problème.

Il existe une configuration de journal des erreurs pour alerter si ce processus s'exécute trop longtemps et il peut être trouvé dans X place.

Je voudrais également ajouter quelque chose comme "Les détails de l'échec, la description des scénarios de rupture potentiels et les solutions possibles peuvent être trouvés dans le chapitre X de la 'Problèmes potentiels et mitigations guide.docx "document". Et puis bien sûr ajouter ce document au contrôle de source / référentiel partagé pour qu'il se déplace avec le code.

En tant que chose sans rapport: je réalise ceci devrait être meilleur en tant que commentaire à l'une des bonnes réponses déjà en place, mais je ne peux pas encore ajouter de commentaires, j'ai donc ajouté une réponse à la place.

Commenter et s'assurer que la mémoire d'entreprise est professionnelle au point que les gens devraient le faire plus souvent.

La différence entre vos première et deuxième versions - la première est émotive ("WAH! ILS DOIVENT FAIRE CECI MAIS NE Donc, c'est tout GONNA DIEEEEE! "). Le second est plus factuel, les connaissances dont ils ont besoin, que c'est ad hoc et susceptible de casser, et ce qui peut techniquement être fait, et que vous voulez qu'ils soient conscients de leur propre travail.

Aucun prix qui c'est mieux.

Votre question confond "opinion" et "émotivité".

L'opinion c'est bien, vous êtes payé pour avoir une vue sur les domaines professionnels: "Pas idéal". "" Le choix d'une solution ad hoc peut poser des problèmes, voici quelques informations et comment je suggérerais d'y remédier ". Ou même" Ce n'est pas le meilleur code de classe que nous ayons écrit, mais le temps presse, ce correctif doit être supprimé et le problème sous-jacent traité lorsque nous pouvons persuader quelqu'un de l'inclure dans le budget ". Ce sont toutes des opinions. Même si elles sont exprimées avec force ou ironie.

L'émotion est inutile et contradictoire:" Branleur de patron a exigé cela pour la vitesse parce qu'il ne se soucie pas du risque de corruption des données "." J'aurais dû utiliser la bibliothèque X, mais des merdes stupides en marketing veulent qu'elle se précipite donc elle va probablement casser, j'ai dû la patcher constamment et mes notes sur la façon de le faire sont dans le fichier Y au cas où quelqu'un d'autre en aurait besoin ". (OK, tout est beaucoup exagéré!)

Dans vos exemples, la phrase clé est" contre mon meilleur jugement ". ou susceptible d'être lu comme) "WAH, QUELS IDIOTES!" C'est ce qui rend votre premier émotive. Quelques autres choses aussi mais c'est le gros. N'ajoute rien sauf "IM PISS ED OFFFFFF ET VEUX QUE LE LECTEUR LE SAIT "

Vous voyez la différence?

Oui, veuillez laisser des commentaires. Même si ce n'est que pour expliquer pourquoi quelque chose a été implémenté, si une partie du code semble plutôt étrange, mais qu'il y avait une raison spécifique de le faire de cette façon, cela aiderait grandement à savoir pourquoi. Sinon, le prochain risque de "réparer" le code étrange juste pour tomber sur une liste d'erreurs.

La façon dont vous formulez les choses dépend de vous, ne pas tenir compte des préférences personnelles peut être une bonne idée. .

Comme expliqué dans "Clean Code" Les commentaires ont tendance à pourrir avec le temps, il est donc inacceptable d'avoir de tels commentaires. De plus, les commentaires sont également considérés comme du bruit: trop de commentaires, et vous devez faire quelque chose de mal.

Si vous avez besoin d'expliquer un algorithme, une implémentation spéciale, une conception ou autre chose, écrivez un document . Expliquez pourquoi quelque chose est implémenté de cette façon et quelles sont les alternatives.