Mon patron veut une explication narrative ligne par ligne de notre code en anglais

155

On m'a spécifiquement demandé de donner, ligne par ligne (ou selon le cas - par exemple, image par image, etc.) des explications ou des commentaires que mon supérieur souhaite pouvoir lire et suivre.

Puisqu'il n'est pas programmeur, il ne peut pas suivre le code, il veut donc que tout soit traduit en anglais.

A-t-on déjà demandé à quelqu'un de faire cela auparavant?

J'ai commenté tout le code source et utilisé JSDoc pour générer une documentation complète de toutes les fonctions, variables, etc., et inclus un exemple d'implémentation, ainsi que des démonstrations complètes avec commentaires.

Y a-t-il autre chose que je puisse faire pour commenter le code pour les non-programmeurs?

Ce n'est pas une demande raisonnable, n'est-ce pas?


MISE À JOUR

Finalement, j'ai réussi à expliquer pourquoi ce n'était pas une bonne utilisation du temps pour faire ce qu'il demandait. C'est un type raisonnable et il ne comprenait tout simplement pas en quoi consiste mon travail. Une fois qu'il a vu ce post, je pense qu'il a rapidement compris que ce n'était pas une demande normale.

J'ai fourni une documentation qui pourrait être suivie par un autre programmeur (commentaires JSDoc et inline - ainsi que quelques notes supplémentaires sur des problèmes techniques), ainsi qu'un très large diagramme de la logique principale du programme à suivre par mon patron.

En fin de compte, toutes les parties étaient satisfaites et nous sommes passés à autre chose.

Billy Moon
la source
Verrouillé pour des raisons historiques, veuillez consulter "Verrouiller les questions fermées avec vote supérieur" pour plus de détails.
Yannis

Réponses:

160

Non , ce n'est pas une demande raisonnable!

Parlez-lui , ou demandez à quelqu'un d'autre de l'en dissuader, par tous les moyens. C'est une idée irrationnelle qui, bien que faisable soit si chère à faire, ne devrait jamais l'être. Une vue d'ensemble des fonctions et des sous-routines est raisonnable, mais "expliquer" chaque ligne de code ne l'est pas. Il serait plus efficace pour lui d'apprendre à lire la langue en main que de le faire.

La prochaine chose qu’il demandera est de traduire des formules mathématiques, ou quoi, en anglais. Bien que cela soit certainement possible, cela introduit beaucoup de marge d'erreur et d'interprétation erronée et ne devrait jamais être fait. Tout comme "traduire" le code en anglais.

Rook
la source
Intéressant: Allez lire les conférences de Richard Feynmans sur la physique. Vous constaterez qu’une grande partie est un argument soigneusement rédigé, en anglais (si X, alors Y doit être vrai, et donc Z ... etc.). Peu de maths. Ce que je veux dire, c'est que vous pouvez expliquer les choses en anglais. Que vous DEVRIEZ ou non, est une autre affaire.
Rapidement maintenant
1
@quickly_now - Lisez-les il y a longtemps au collège. Pas mal lu. Je suis d'accord, vous pouvez l'expliquer - vous pouvez l'expliquer dans n'importe quelle langue lorsque la personne à qui vous expliquez comprend déjà "l'abstraction" qui se cache derrière (code, équation mathématique et signification de celle-ci ...) // S'il ne le fait pas t - vous aurez du mal à l'expliquer dans n'importe quelle langue.
Rook
4
@Rook - bon point. Expliquer la mécanique quantique à une tribu primitive dont le vocabulaire est limité à la direction dans laquelle s'est déplacé le wapiti serait plutôt difficile.
Rapidement maintenant
Je pourrais parfois obtenir «l'intention» de votre responsable de micro-gérer. Mais, si le code était très clair en lui-même, il peut simplement le lire sous forme de texte anglais.
Arvind Chinniah le
150

Avez-vous des documents de conception ? Voilà l'explication anglaise de ce que le code fait. Un gestionnaire non programmeur ne devrait pas avoir besoin de plus que cela.

xtian
la source
15
C'est pourquoi j'ai précisé: "Un gestionnaire non programmeur ne devrait pas avoir besoin de plus que cela."
Malfist
35
@ Loren Pechtel: J'aimerais y placer le site et regarder ce mec lire des pages de "Créez une variable entière nommée X. Définissez-la sur 0. Créez une variable entière nommée Y. Définissez-la sur 0. Créez une variable entière nommée Z Définissez-la sur 0. Créez une variable entière nommée Position X. Définissez-la sur 0. Créez une variable entière nommée Position Y. Définissez-la sur 0. Créez une variable entière nommée Position Z. Définissez-la sur 0. Créez une variable entière nommée Rotation X. Définissez-la sur 0. Créez une variable entière nommée rotation Y. Définissez-la sur 0. Créez une variable entière nommée Rotation Z. Définissez-la sur 0. "...
FrustratedWithFormsDesigner
9
@Frustated C'est beaucoup plus facile avec la coloration syntaxique! " [p32767, l21, c8] Augmente pXla taille d'un Integer. Augmente Sumla valeur indiquée par pX. Augmente ide 1. Si iest inférieur à 3, allez à la page 32768, ligne 17, colonne 42. Sinon, passez à la page 32767 , ligne 21, colonne 8. "
Mateen Ulhaq
9
@muntoo, vous devez intégrer toutes ces fonctions pour ne pas avoir à naviguer entre les pages. Sinon, on pourrait avoir beaucoup de difficulté à remonter dans la pile.
Kibbee
15
@Frustrated: Alors, quelle voix imaginez-vous? Je ne peux pas décider entre Sean Connery et Morgan Freeman.
Bêta
113

Existe-t-il un prix de micro-manager de l'année? Il semble que votre patron mérite une nomination. Quelqu'un qui pense avoir besoin d'une compréhension ligne par ligne du code, mais ne veut pas apprendre à le lire directement, est aussi parfait que le micro-gestionnaire que l'on puisse imaginer.

L’un des avantages d’être développeur est que la difficulté de comprendre le code empêche la microgestion au-delà d’un certain degré, du moins au niveau de la mise en œuvre détaillée, du moins pour une gestion non technique, car même le microgestionnaire le plus dur reconnaît qu’il est sur leur tête à ce niveau. Mais le génie de votre patron pourrait trouver le moyen de briser le rideau de silicium.

Et, en prime, la traduction perd énormément de temps, avant même qu’il utilise la traduction anglaise pour suggérer diverses améliorations (je suppose qu’il sait coder mieux que les programmeurs, même s’il ne peut pas lisez le code et pourrez partager sa sagesse dès que quelqu'un le traduira, sinon pourquoi aurait-il besoin de traduire chaque ligne?).

Donc, non, ce n'est pas une demande raisonnable, et je n'en avais jamais entendu parler auparavant. Et je me sens pour toi. Je pense que tout le monde devra peut-être commencer discrètement à chercher un autre emploi, car une fois qu'il commencera à utiliser la traduction de code comme outil de gestion, ce sera probablement un lieu de travail brutal (euh, un lieu de travail plus brutal).

Sur le plan positif, peut-être que vous pouvez obtenir un nouvel anti-pattern nommé d'après votre situation? Que diriez-vous de l'anti-pattern "Dirty Hungarian Phrasebook", d'après le sketch de Monty Python, dans lequel un buraliste tente de communiquer avec une personne qui ne parle pas anglais en utilisant un livre de phrases en hongrois dont les traductions sont comiquement fausses?

psr
la source
21
+1 pour le diagnostic de la microgestion. Dans mes propres mots: sortir le f___ de là!
tdammers
@tdammers: heureusement, c'est le genre de chose que je peux dire à mon patron. C'est un bon gars en plus d'être un patron!
Heltonbiker
5
Un gestionnaire qui doit comprendre chaque ligne du code s'appelle un programmeur.
James P.
91

Asseyez-vous avec lui et parlez-lui de 10 lignes du code. Expliquez chaque détail jusqu'à ce que vous soyez tous deux d'accord pour le comprendre.

Peut-être que cette expérience est tout ce qu’il recherche: une simple impression de votre travail et de l’apparence du logiciel de votre point de vue. C'est une bonne chose dans mon livre.

Si, après cela, il veut toujours que vous continuiez, dites: notez le nombre de questions que je devais poser; imaginez si j’aurais dû expliquer tout cela sans pouvoir poser de questions, comment aurais-je pu savoir quoi inclure et quoi laisser de côté? Combien de temps aurait-il fallu avant que les résultats vous soient utiles? Maintenant combien de lignes voulez-vous que je fasse de cette façon?

Reinierpost
la source
57
Assurez-vous qu'après avoir passé deux heures à expliquer à dix lignes, il comprend qu'il reste 50 000 lignes de code (ou autre) à expliquer.
HLGEM
6
En fait, une façon très saine de faire un suivi. Faites-lui voir l'ignorance de ses voies.
Kibbee
4
@reinierpost: votre méthode est du génie pur.
Heltonbiker
5
Si vous voulez faire cela, dites d'abord au patron pourquoi c'est une mauvaise idée en général et ALORS démontrez. Si vous ne le faites pas, vous aurez peut-être l'impression de lui tirer un "tour" et de le mettre sur la défensive.
nerdytenor
5
Ne jamais dire aux gens que leurs idées sont mauvaises !! Vous pouvez toutefois discuter de ce qui serait nécessaire pour les concrétiser et peut-être même donner quelques idées pour prendre des raccourcis. Si cela les amène à conclure que l'idée n'était pas viable ou à transformer l'idée initiale en une chose complètement différente, et qu'ils devraient le remarquer à un moment donné, ils hausseront les épaules et diront: c'est la vie.
Reinierpost
43

Je ne pense pas que ce soit une demande raisonnable. SOURCE CODE n'est pas destiné à être lu en anglais (ni dans aucune autre langue d'ailleurs).

Il a peut-être peur que votre code fasse quelque chose qu'il n'approuve pas ou dont il n'a pas connaissance. Si tel est le cas, je ne pense pas que vous puissiez faire quelque chose à ce sujet. Vous devrez écrire la documentation ou peut-être le convaincre d'embaucher quelqu'un pour vérifier votre code.

Pablo Santa Cruz
la source
13
Même avec une traduction en anglais , un non-programmeur peut très bien croire:/* and this line is transferring deposits to the correct account */ deposits.TransferAll(acctInfo);
Résumé du
15
Si le patron a "peur que votre code fasse quelque chose qu'il n'approuve pas ou n'est pas au courant", cela ne fera rien pour apaiser ses craintes. La même personne fournit la traduction qui a écrit le code. Qu'est-ce qui les empêche de mentir sur ce qu'il fait? Il se passe autre chose ici.
mmc
4
COBOL devait être lu en anglais.
Oosterwal
1
Peut-être essaie-t-il de comprendre ce que le code fait pour voir s'il est d'accord avec le raisonnement et peut-être avoir de meilleures idées. En tout cas, ce n'est pas son travail de le faire, du moins pas de cette façon ...
heltonbiker
32

C'est vraiment très simple:

  • Vous avez été embauché en raison de vos compétences en tant que programmeur
  • Votre manager n'a pas ces compétences
  • Ergo, votre responsable ne devrait pas raisonnablement s'attendre à être en mesure de bien comprendre ce que vous faites.

J'ai eu une expérience similaire à celle d'un emploi précédent. Mon responsable était un comptable (donc très attentif aux détails) et ne comprenait pas ou n’avait pas vraiment confiance en la programmation. Elle ne pouvait pas comprendre que, en tant que personne non technique, elle ne devrait pas être en mesure de saisir la minutie de ce que j'ai écrit. Après de nombreuses demandes de documentation excessive et des demandes de formation d'utilisateurs non techniques à la gestion et à la modification du code (oui, vraiment), j'ai arrêté d'essayer de la reprendre, et j'ai carrément refusé. L'analogie que j'avais l'habitude d'expliquer était simple:

  • Je ne suis pas comptable
  • Je ne devrais pas m'attendre à comprendre chaque transaction ou chaque enregistrement dans nos comptes
  • Cela ne signifie pas que les comptes sont faux ou indignes de confiance, simplement parce que je ne les comprends pas.
  • Ceci est rendu possible en faisant confiance à la personne qui les a compilés

Au bout du compte, voici à quoi ça ressemble, à mon avis: un gestionnaire qui a du mal à faire confiance à ses employés; ou craint qu'ils ne partent, et pense que c'est un moyen efficace de l'atténuer.

La seule solution à cela est de s'asseoir et d'expliquer pourquoi cela n'a pas de sens. Il vous appartient de comprendre le code et de permettre à une personne possédant les mêmes compétences de le comprendre, pas à celle de votre responsable. Leur montrer ce fil peut être une bonne idée (ou une très, vraiment terrible, selon leur personnalité).

John N
la source
comment votre manager a-t-il pris votre explication?
Jeff Martin
1
Exactement aussi bien que vous pourriez vous y attendre. ;) Cependant, le point était fait et les demandes arrêtées. Je ne sais pas si c'était parce que je l'avais convaincue de la validité de mon argument ou qu'elle avait décidé que cela ne valait pas la peine et a abandonné.
John N
25

Ligne par ligne, c'est ridicule. Ce que je pourrais suggérer, c'est proposer de générer des documents à partir de commentaires et de le lui donner. C'était suffisant pour un certain nombre de subventions et d'audits du gouvernement canadien sur lesquels j'ai travaillé par le passé.

Il n'obtiendra pas ligne par ligne, mais il obtiendra méthode par méthode, ce qui devrait quand même être plus détaillé qu'il ne le faut.

Quelques solutions existantes, selon votre plate-forme:

  • C #: château de sable
  • Java: javadoc
  • "C ++, C, Java, Objective-C, Python, IDL (versions Corba et Microsoft), Fortran, VHDL, PHP, C # et, dans une certaine mesure, D." : doxygen
Steven Evers
la source
Comme il y a Pas2Dox, ajoutez Delphi à la liste des doxygènes ;-)
Fabricio Araujo
Allez sur le lien Sandcastle. Regarde impressionné. Cliquez sur l'onglet "Documentation". Voir le message "Ce projet n'a pas encore de documentation." Regardez moins qu'impressionné.
Kaz Dragon
16

Il serait beaucoup plus rapide pour lui d'apprendre à lire le code que de traduire l'intégralité du code de toute application intéressante en anglais. En plus, on a essayé ça avec COBOL et ça n’a pas aidé du tout. S'il ne veut pas apprendre, mais veut juste faire de son ignorance le problème de quelqu'un d'autre, vous avez un patron très pointu.

Kevin Cline
la source
3
Je pense que l'anglais devrait être la langue. Le patron doit demander que tous les logiciels soient écrits dans un DSL (langage spécifique à un domaine), puis il peut modifier le fonctionnement du système.
David d C e Freitas
Je pense que la mention de Cobol le résume. Quiconque a imprimé un monde simple et bonjour sait à quel point cette langue est ridiculement verbeuse. C'était un bon pas vers quelque chose d'intelligible, mais beaucoup trop formel.
James P.
15

Utilisez votre expertise technique pour poursuivre votre patron.

  1. Dites-lui qu'il faudra autant de temps pour le faire que pour le coder (vous pouvez le rendre plus long).
  2. Demandez-lui comment ce document doit être mis à jour. Informez-le que tous les changements de code prendront au moins deux fois plus longtemps.
  3. Si vous ou quelqu'un d'autre trouvez des bogues, demandez-lui si vous devez les corriger maintenant ou attendez d'avoir terminé le codage Psuedo. Rappelez-lui les numéros 1 et 2.

Comme toutes les suggestions de mauvaises solutions, il est préférable d'identifier le problème. Votre supérieur est peut-être confronté à des questions techniques de la part de la haute direction et il se sent embarrassé de ne pas pouvoir y répondre. Il pense qu'il pourrait être particulièrement préoccupé par une partie du code, de sorte que vous pourriez limiter cette entreprise de grande envergure à cette zone.

En soumettant un échantillon, il peut en venir à la conclusion que si vous ne comprenez pas comment fonctionne le codage (qu'est-ce qu'une boucle et que fait-elle à tous ces éléments?), Le langage utilisé n'a pas d'importance. Il est meilleur comprendre l’application du point de vue d’un utilisateur expérimenté. Je pense qu'il est juste que vous lui disiez que vous préférez écrire un vrai code / indice - je cherche un autre emploi.

JeffO
la source
7
nous devons faire attention de ne pas qualifier quiconque d '"idiot". Même si cela nous satisfait personnellement en tant que programmeurs, je ne pense pas que ce soit professionnel, et toute demande émanant d’un responsable, quelle que soit sa singularité, devrait être traitée en fonction de ses mérites.
funkymushroom
6
@funkymushroom: Le mérite de cette demande est qu'il est un idiot.
DeadMG
3
@funkymushroom - Je pense que nous pouvons avoir droit à un peu de légèreté sur ce site. Après tout, vous passez par funkymushroom.
JeffO
2
@ Jeff: Point bien pris. Je ne suis en aucun cas un bâton-dans-la-boue. Il existe cependant deux types d '"idiot". Le "malicieux imbécile" et le "ignorant idiot" et j'ai travaillé avec les deux. Le premier devrait être ignoré, il est dangereux pour notre carrière, et le second peut être un bon allié, nous devrions donc lui apprendre.
funkymushroom
@funkymushroom - d'accord, alors je l'ai sorti.
JeffO
12

Pourquoi?

Un commentaire ligne par ligne n'est pas raisonnable, mais voici ce que je demanderais: pourquoi voulez-vous cela?

Est-ce parce que ...

  • vous voulez une compréhension complète de ce que fait le logiciel (pas nécessairement comment)?
  • vous voulez être sûr qu'un autre programmeur peut prendre en charge le projet si je pars?
  • tu veux voir que je fais du vrai travail?

Cette demande peut susciter un désir raisonnable et vous pourrez peut-être faire plaisir à votre patron en le découvrant et en répondant à ce besoin.

Mise à jour

Sur la base des Mikey'scommentaires, j'ai peut-être dit cela un peu trop brutalement. Je ne veux pas dire que vous devriez littéralement dire "pourquoi voulez-vous cela?", Juste que vous devriez le découvrir . La formulation et le ton de la voix font une grande différence. Plus précisément, vous pourriez dire quelque chose comme:

"J'ai réfléchi à votre demande d'avoir une explication de chaque ligne de code. C'est un peu inhabituel de faire les choses de cette façon. Je me demandais s'il y avait quelque chose que je ne vous ai pas bien communiqué à propos de mon travail. Qu'est-ce que vous voulez vraiment comprendre de notre code ou de ce que je fais? Qu'est-ce que vous essayez d'accomplir ici? "

Bien sûr, il est possible que votre patron soit totalement déraisonnable. Mais il est plus probable qu'il ne sache pas à quel point cette demande est bizarre et a un objectif rationnel en tête.

Sinon, commencez à polir votre CV. :)

Nathan Long
la source
-1 pour cette réponse: Si vous voulez conserver votre emploi (ou au moins le quitter volontairement), vous ne devriez pas demander à un tel patron "pourquoi"? C'est quelque chose qui doit être raffiné, comme d'autres l'ont suggéré.
Vecteur
3
Je ne suis pas d'accord avec le commentaire de Mikey. Suivre aveuglément les ordres est stupide. Demander «pourquoi? chaque demande m'a permis d'économiser d'innombrables heures de travail inutile et d'économiser beaucoup d'argent à mon entreprise. C'est ce qu'on appelle la consultation, et ceux qui ne craignent pas leurs chefs le font généreusement et à bon escient. Quand les gens qui travaillent pour moi suggèrent quelque chose, je leur demande aussi «pourquoi? ainsi que. Dans les deux cas, il demande une justification et il est parfaitement acceptable de le faire.
Soviut
10

Cela semble être une bonne occasion d'essayer une programmation alphabète. Recherche le sur Google. :)

Mais ... ce n'est pas nécessairement une demande totalement déraisonnable. Une partie de votre travail (la partie la plus importante, imo) consiste à communiquer votre (vos) algorithme (s) à d’autres développeurs et, le cas échéant, à des personnes non techniques. Les programmeurs de génie solitaire qui ne peuvent pas communiquer sont toujours problématiques, je pense.

Pour cela, votre code doit être parfaitement clair (signification: soit vraiment auto-documenté, soit bien documenté, et par "auto-documenté", je veux dire que les variables et les fonctions ont un sens ou une responsabilité et leurs noms le reflètent clairement). Votre patron peut avoir de bonnes raisons pour sa demande. Peut-être (je devine juste ici) que votre prédécesseur ou vous-même avez la réputation d’être un code impénétrable et fragile et qu’il s’agit là du remède de votre patron. C'est un peu extrême, mais pourrait être un exercice utile pour vous. Je suppose qu'il sait qu'il faut du temps pour rédiger de meilleurs documents (et s'il ne le fait pas, il devrait être éduqué - c'est comme écrire un terme: il faut plus de temps pour écrire que pour lire).

JohnL4
la source
J'ai jeté un coup d'œil à la page Wikipedia. Cela me rappelle le "structuré <insérer le langage humain ici>" que j'ai vu pendant les études. Vous utilisez le langage humain pour représenter ligne par ligne la structure de programmation avec des expressions comme if blah then add 1 to xalternative au nassi-schneiderman ou aux organigrammes. Est-ce ce que l'on entend par programmation alphabète?
James P.
Vous êtes le seul sur cette page, qui a mentionné la programmation littéraire de Knuth - me fait me demander sous quel rocher le reste des affiches a vécu pendant les quarante dernières années ...
cji
@ James: achetez un exemplaire de "Tex - le programme" de Knuth et lisez-le. C'est une programmation alphabète.
cji
10

Même une traduction ligne par ligne ne traduira pas efficacement la signification de chaque ligne de code. La compréhension par les programmeurs d’une ligne de code est toujours liée à de nombreux facteurs. Entrez dans quelque chose comme un morceau de code multi-thread et la traduction anglaise n'aura pas plus de sens que le code brut. Pensez aux fonctionnalités réparties entre plusieurs fonctions / fichiers. Certains codes n'ont absolument aucun sens sans expliquer des quantités importantes d'autres codes. Essayez d'expliquer les différentes parties impliquées dans l'injection de dépendance "ligne par ligne" et vous verrez ce que je veux dire. Pratiquement tout ce qui va au-delà du code de procédure fonctionnant selon Dieu nécessitera une connaissance approfondie de la programmation, juste pour comprendre la traduction anglaise. Regardez aussi quelque chose d'aussi simple qu'une déclaration de décision if / else. Il n'y a pas de ligne par ligne, puisque la ligne suivante dépend des données d'exécution. La ligne suivante pourrait être l’une des nombreuses possibilités.Lorsque vous aurez expliqué le rôle de votre application, vous aurez transformé votre MP en programmeur et vous aurez tous deux cinq ans de plus.

Morgan Herlocker
la source
10

Depuis que j'enseignais la programmation, je ne serais que trop heureux de l'essayer.

Il va vite se rendre compte qu'il en a plus que ce qu'il avait prévu, ce qui me rend triste parce que j'aime expliquer les choses :-)

Mike Dunlavey
la source
3
Je pense que c'est la meilleure réponse ici. Je ne comprends pas toute la réticence à essayer, je veux dire que vous allez être payé pour rester assis à expliquer votre code! Enfer, à moins que votre code ne soit complètement nul, vous l'apprécierez probablement et, peu importe sa qualité, vous trouverez probablement des bugs et des améliorations à apporter.
Bill K
1
Un enseignant m'a expliqué des choses lors de la saisie du code affiché à l'aide d'un projecteur. Peut-être que cela pourrait être fait un peu comme une leçon de conduite. Si vous ne pouvez pas au moins tout le code, vous pouvez donner une meilleure idée de ce qui est fait et de la manière dont vous le faites.
James P.
1
J'essaie moi-même d'entrer dans le secteur de l'enseignement et j'ai donné une réponse similaire. Je suis avec @ Bill, je suis sérieusement déçu que les gens adoptent une attitude si solitaire. Sommes-nous foutus en pensant qu'il vaut la peine de passer du temps à expliquer même une petite partie du code?
Rei Miyasaka
1
@Rei: Les attitudes, bonnes ou mauvaises, ont tendance à s'emparer de larges sous-ensembles de personnes par ailleurs similaires. J'ai eu une vaste expérience (ingénieur, étudiant diplômé, professeur, consultant, employé de longue date), alors j'aime penser que cela donne une perspective. De plus, mes attitudes ont changé au fil des ans.
Mike Dunlavey
10

Lorsque vous vous référez à votre "patron", s'agit-il d'un "cadre intermédiaire en charge de vous / de votre équipe"? ou le propriétaire de votre entreprise? Êtes-vous payé "à l'heure" ou "sur un salaire"?

Si votre patron est un gestionnaire de niveau intermédiaire responsable, parlez-lui de son patron, soulignez que, pour répondre à ses besoins, votre productivité au sein de l'entreprise sera réduite à un tiers de ce qu'elle pourrait être.

SI votre patron est "le gars qui signe les chèques", expliquez-lui la même chose, mais avec plus de diplomatie. Votre travail est passé de "Écrivez le code" à "Écrivez le code, écrivez l'explication du code, expliquez-le."

entrez la description de l'image ici

Cos Callis
la source
Pourquoi ne pas le faire et prendre l'argent? Êtes-vous tellement sûr que votre seule valeur est de produire du code comme un singe?
Bill K
9

Un organigramme sera probablement plus avantageux pour lui. Il s’agit là d’une demande inhabituelle qui ne dit pas grand-chose de lui en tant que responsable.

James
la source
18
En fait, cela m'en dit long sur cette personne ...
Marjan Venema
5
C’est ce que «ne parle pas beaucoup» signifie dans ce contexte - cela en dit beaucoup, certes, mais cela n’indique tout simplement rien de bon pour l’individu.
Joseph Weissman
8

Le fait que votre patron soit disposé à passer un peu de temps à comprendre le code que vous avez écrit pourrait être utilisé à votre avantage. Essayez de lui présenter Concombre: http://cukes.info/

et demandez à votre patron d’écrire le test BDD pour vous à l’avenir.

moonflash
la source
Je cherche depuis quelque temps à utiliser le concombre dans mon magasin ... malheureusement (ou peut-être heureusement!), Mon chef se fiche de ce qui se passe dans les coulisses, du moment que cela fonctionne. Lui faire comprendre l’intérêt d’écrire des tests a été une bataille ardue.
Jason Lewis
6

Il ne devrait pas prendre la peine de le savoir. Dites-lui que l'implémentation du développement logiciel est sujette à changement. La conception de l'événement est sujette à changement. Parlez-lui de la dissimulation d'informations, de l'encapsulation et de l'abstraction.
En tant que membre de votre équipe, en tant que client de votre code, il ne doit travailler que dans le cadre d’une abstraction claire et de haut niveau de ce que fait votre code. De la même manière, n'importe quelle couche de votre code fonctionne avec une autre couche du code de quelqu'un d'autre. En savoir plus que cela ne le ralentira et le mettra en danger de faire des suppositions basées sur le fonctionnement interne de votre code. Ces hypothèses cesseront de tenir lorsque vous devrez modifier votre code, ce qui deviendra un problème s'il construit tout type de système ou de processus basé sur celles-ci.
Et avoir à faire ce genre de travail réduira votre efficacité. Vous devrez non seulement apporter des modifications ultérieures à deux endroits différents, mais cela affectera également votre moral au travail, ce qui réduira encore plus votre rendement.

back2dos
la source
6

La beauté de l'anglais réside dans le fait qu'elle obfucate magnifiquement. Si vous utilisez ceci à votre avantage, vous ne pourrez peut-être plus jamais traiter ce type de demande. Je prendrais un petit extrait du code comme exemple, mais celui-ci est très abstrait et pas du tout facile à comprendre. J'écrirais ensuite les commentaires en anglais technique comme si vous écriviez un chapitre dans un livre de programmation. Plus long et compliqué à suivre, mieux c'est. Dites-lui combien d'heures il vous a fallu pour documenter cette fonctionnalité. Expliquez ensuite qu'il ne s'agit que de 1 / 10ème de 1% (utilisez des chiffres réels basés sur des lignes de code si vous le pouvez, ils sont probablement pires que cela) de la base de code réelle. Lorsqu'il se rend compte qu'il n'a aucune idée de ce que dit la traduction anglaise et qu'il faudra 20 000 heures-homme pour réaliser ce niveau de documentation, il reculera assez rapidement. Mais soyez très sérieusement en train d'accomplir sa tâche. N'essayez pas cela si vous ne pouvez pas retirer ça et qu'il soupçonne que vous le jouez.

HLGEM
la source
6

Cela ressemble à un candidat pour un strip spécial Dilbert ! Sa demande ne certainement pas un son raisonnable à première vue.

En dehors de l'humour, essayez de trouver ce dont il a réellement besoin et pourquoi, puis informez-le de ce que cela lui coûtera en dollars ou en heures, et laissez-le décider s'il souhaite dépenser autant d'argent.

Quant à vous, comptez le nombre d'heures qu'il vous faudra pour répondre à sa demande apparemment bizarre, puis déterminez s'il ne serait pas préférable d'investir une fraction de ce temps pour trouver un nouvel emploi pour un employeur disposé à vous traiter. en tant que professionnel!

John Tobler
la source
1
Une analyse coûts-avantages devrait faire l'affaire. Peut-être que le gestionnaire a des avantages supplémentaires à apporter. S'il ne paye pas, il est difficile de faire appliquer et de défendre à la haute direction.
mbx
6

Amenez-le dans votre bureau et faites-lui visiter votre code.

Il se rendra compte en partie qu'il a fait une demande absurde, il s'en ira et ne vous dérangera plus jamais.

Si vous ne cédez pas à ses exigences pour l'aider à essayer de comprendre votre code, il trouvera des moyens différents mais tout aussi absurdes de vous attaquer.

C'est un cas où l'apaisement fonctionne mieux que l'abrasion.

Rei Miyasaka
la source
+1 - Je pensais dans le même sens - je le prends à la demande - il va probablement s'ennuyer et / ou avoir peur de mourir avant trop longtemps ...
Vector
+1 j'aime ça - "fonctionne mieux que l'abrasion".
Mike Dunlavey
6

Ce serait très bien si nous avions un traducteur "Langue X vers anglais" qui fait cela. Ensuite, on pourrait sourire et dire, pas de problème, patron, vous aurez ça dans une minute. Et puis vient un courrier avec quelques mégaoctets de texte qui se lit comme suit:

  • Soit a un nouveau tableau entier de 20 éléments.
  • Soit x une variable pour stocker des entiers.
  • Mettre x à 0
  • Bien que x soit inférieur à 20, faites ce qui est prescrit dans les 2 lignes suivantes
  • définir l'élément de tableau de a avec l'index x sur le résultat de l'appel de nThPrime avec l'argument x + 1
  • augmenter x de 1
  • ....

Une autre option serait de proposer désormais une programmation à Shakespeare .

Ingo
la source
J'allais faire la même suggestion. Le patron ne veut pas d'un aperçu conceptuel, il le veut ligne par ligne, de sorte qu'il devrait être possible de créer quelque chose en un jour ou deux qui crée une documentation totalement inutile mais superficiellement correcte. Peu importait qu’il s’agisse d’un nid de rats d’iels-in en perl facilement confondu par les cas de coin, cela identifierait simplement les déclarations de variable, les modifications de variable, les appels de méthode, etc. manière groks le code).
PhilDin
Oui, ce patron est juste ignorant. Il ne sait pas ce qu'est "l'abstraction", il ne sait pas que l'anglais n'est pas bon pour exprimer des programmes informatiques, il ne peut pas imaginer qu'il ne veut vraiment pas connaître tous ces détails, c'est pourquoi il paye un programmeur. Par conséquent, il mérite une leçon comme celle-ci.
Ingo
5

Mon patron veut une explication narrative ligne par ligne de notre code en anglais

Dure.

Puisqu'il n'est pas programmeur, il ne peut pas suivre le code, il veut donc que tout soit traduit en anglais.

S'il n'est pas programmeur, il ne devrait pas lire le code. Du tout.

Fournissez plutôt une documentation de haut niveau.

Ce n'est pas une demande raisonnable, n'est-ce pas?

Non.

Courses de légèreté en orbite
la source
4

En tant que programmeur, vous avez vraiment "deux" emplois.

La première consiste à créer de bons programmes. La seconde consiste à les "vendre" à des clients internes et externes à l'entreprise.

La demande de votre patron "blesse" votre premier emploi. Il faut plus de temps pour documenter vos programmes. D'autre part, il vous oblige en réalité à travailler plus fort sur votre "deuxième" emploi.

Votre patron vous demande de documenter votre programme en anglais pour son bénéfice, et probablement pour le bénéfice des personnes avec lesquelles il doit traiter, à l'intérieur et à l'extérieur de l'entreprise. Si vous l'aidez à faire son travail, cela fonctionnera à votre avantage à long terme, lorsque vous lui demanderez plus de matériel, de personnel ou plus d'argent pour des augmentations de salaire. Après tout, il vous a demandé de faire plus de travail.

Tom Au
la source
3
Documenter ligne par ligne! = Vendre le projet. Il devrait déjà exister un document fournissant ces informations, appelé exigences. Je suis d’accord sur vos 2 descriptions de poste, mais la documentation à ce niveau ne sera pas bénéfique pour la vente du projet / système / application. Il y a un niveau approprié de documentation pour présenter votre travail, et ce n'est pas ça.
cdkMoose
Je parie que la personne qui écrit les chèques dans cette entreprise ne serait pas heureuse que ce responsable gaspille autant de ressources de l'entreprise.
JeffO
@ Jeff O: Pourrait être. Ou peut-être que la société ENTIÈRE est comme ça, jusqu'au sommet.
Tom Au
4

Je pense que BDD conviendrait bien avec ce problème, même s'il semble que votre projet est sur le point d'être achevé. Il est donc difficile de le mettre en œuvre maintenant, ce qui en fait plutôt une référence future.

Avec BDD, les cas d'utilisation sont décrits comme des documents lisibles par l'homme, qui sont ensuite traduits en tests fonctionnels automatisés.

Inoryy
la source
C'est peut-être la suggestion la plus constructive à ce jour. Le développement axé sur le comportement est conçu pour répondre exactement à ce besoin: aider les programmeurs et leurs responsables / clients à se mettre d'accord sur les tâches du logiciel. La rédaction des descriptions aide à planifier le code et l'exécution des tests prouve qu'il s'agit toujours de descriptions précises.
Nathan Long
4

Probablement, cette demande est un bon moment pour apprendre des choses comme ANTLR . Prenez ANTLR, prenez la grammaire de votre langue, analysez tout le code que vous avez, parcourez votre AST en générant des descriptions basées sur des modèles pour chaque nœud, ainsi i++est décrit increase i by 1 using postfix increment operator. Cela devrait être vraiment drôle. Votre patron peut également souhaiter que cet outil soit inclus dans le script de génération. Ainsi, chaque fois que vous apportez des modifications, il recevra un courrier électronique d'environ 20 Mo décrivant le fonctionnement de la nouvelle version.

PS Je plaisante, c'est un idiot.

Peter Mortensen
la source
3

Bien que je convienne que cette demande est déraisonnable, votre patron peut apprécier quelque chose comme la sortie de Docco , qui sépare votre code et les commentaires ligne par ligne ou clause par clause en une sortie HTML à deux colonnes, avec le code inséré dans une colonne. côté et prose de l'autre. Vous devez taper les commentaires vous-même, bien sûr, mais la présentation est plutôt sympa à mon humble avis, même pour les lecteurs non techniques. Voir, par exemple, une section commentée ligne à ligne du code annoté pour Underscore.js . Il existe également des versions de script Python et shell.

btown
la source
C'est l'une des réponses les plus utiles que j'ai vus pour la question. J'ai effectivement essayé d'utiliser docco, mais j'ai constaté qu'il rencontrait des problèmes avec certains de mes commentaires existants et qu'il était mal interprété. J'ai donc choisi JSDoc à la place et ai suivi les instructions de Google pour générer la documentation. Pas aussi joli, mais très complet, et aussi un format standard. Le problème avec docco pour moi est que vous devez structurer votre code en fonction des commentaires, sinon cela n’a aucun sens. Merci pour la suggestion.
Billy Moon
3

Il est possible que votre patron soit simplement mal informé et intimidé, mais qu'il soit en fait une personne raisonnable. Si tel est le cas, raisonner avec lui / elle pourrait fonctionner - une conversation informelle dans laquelle vous promettez de fournir "ce qu'il veut vraiment", c'est-à-dire; un guide en prose sur ce que fait le programme.

S'il s'agit de "mon chemin ou de l'autoroute", vérifiez votre consommation d'essence maintenant.

Ddyer
la source
3

Vous pourriez écrire des tests d'acceptation à l'aide d'un cadre de conception basé sur le comportement, tel que le concombre ? Cela n'expliquera pas le code. il expliquera ce qu'il fait et en langage naturel. Il a également l'avantage d'être exécutable. Vous pouvez donc toujours être sûr que la documentation est à jour, car si ce n'est pas le cas, le lanceur de test sera rouge.

Découvrez la vidéo d'introduction. Peut-être que c'est une bonne diversion pendant que vous trouvez un nouveau patron ... ;-)

Peter Mounce
la source
2

Votre directeur est presque certainement troublé par le fait qu'il ne comprend pas ce que les gens font qu'il gère, et il n'a pas l'expérience nécessaire pour comprendre les résultats qu'ils produisent.

Je doute qu'il ait bien réfléchi à cette solution, et cela lui a probablement paru judicieux au premier abord. Mais c'est en grande partie parce qu'il ne comprend pas ce qu'est le code de programmation.

Tout programmeur comprend l'absurdité de cette requête, mais nous le faisons parce que nous savons intuitivement qu'une fois que vous avez dépassé le langage, tout ce qui est révélé est l'algorithme, qui est tout aussi cryptique.

// Set s to the first address in the server list
server_info *s = cmd->servers;
// Loop until s is NULL
while (s) {
    // call the server's init function passing our current ID and address
    s->init(proc->id,*addr);
    // call log::info with our custom message
    log::info("Starting server %s",s->name);
    // Set s to the value returned by the server's next() function
    s=s->next();
} // end of loop

Le problème ici est que, même si les commentaires expliquent ce que fait chaque ligne, vous n’avez toujours aucune idée de ce que fait réellement le code, à moins que vous ne compreniez toutes les implications. C'est évident si vous êtes programmeur et avez déjà vu ce modèle. mais montrez ceci à quelqu'un qui ne comprend que les ventes, et il sera tout aussi confus après avoir lu les commentaires qu'auparavant.

Vous pourriez en fait gagner du temps en enseignant à votre patron une programmation de base. S'il veut lire votre code, donnez-lui les outils pour pouvoir le faire. La plupart des langues utilisent une syntaxe assez compacte et l'apprentissage de la structure ne prend qu'une heure ou deux. Il abandonnera presque certainement après quelques jours, mais au moins, il saura ce qu'il transmet et, plus important encore, pourquoi il ne veut pas lire votre code.

tylerl
la source
1

IMHO ... s'il est responsable de la tâche, il devrait savoir comment ça marche ... :)

John K.
la source
2
Faites-vous référence au gestionnaire ou au programmeur?
Nathan Long
Combien d'entreprises peuvent se permettre que chaque responsable non technique utilise autant de temps de développement?
JeffO