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

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.

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.

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.

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?

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?

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.

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é).

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

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.

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.

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. :)

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).

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.

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 :-)

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."

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.

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.

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.

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.

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!

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.

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 .

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.

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.

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.

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.

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.

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.

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 ... ;-)

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.

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