Mon patron veut une explication narrée ligne par ligne de notre code
On m'a spécifiquement demandé de donner ligne par ligne (ou le cas échéant - par exemple, image par image, etc.) une explication ou un commentaire que mon patron souhaite pouvoir lire et suivre.
Comme il n'est pas programmeur, il ne peut pas suivre le code et veut que tout soit traduit en anglais.
A-t-on déjà demandé à quelqu'un de le faire?
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 et des démos de travail complètes avec des commentaires tout au long.
Puis-je faire autre chose 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 gars 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 convient à un autre programmeur à suivre (JSDoc et commentaires en ligne - ainsi que quelques notes supplémentaires sur les problèmes techniques), et un organigramme très large de la logique principale du programme que mon patron doit suivre.
Au final, toutes les parties ont été satisfaites et nous sommes passés à autre chose.
Non, ce n'est pas une demande raisonnable!
PARLEZ-EN DE LUI, ou demandez à quelqu'un d'autre d'en parler, par tous les moyens. C'est une idée irrationnelle, qui, bien que faisable, est si chère à faire, ne devrait jamais être faite. Une vue d'ensemble des fonctions et des sous-programmes 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 autre chose en texte anglais. Bien qu'il soit certainement possible que introduit beaucoup de place pour l'erreur et la mauvaise interprétation, et ne devrait jamais être fait. Tout comme "traduire" du code en anglais.
Avez-vous documents de conception ? Ce sont les explications en anglais de ce que fait le code. Un gestionnaire hors programmation ne devrait pas avoir besoin de plus que cela.
Existe-t-il un micro-manager de l'année? Il semble que votre patron mérite une nomination. Quelqu'un qui croit avoir besoin d'une compréhension au niveau ligne par ligne du code, mais qui ne veut pas apprendre à le lire directement, est à peu près aussi parfait que le micro-gestionnaire que l'on puisse imaginer.
Un avantage d'être un développeur est que la difficulté de comprendre le code empêche la microgestion au-delà d'un certain degré, au moins au niveau de la mise en œuvre détaillée, au moins par la gestion non technique, parce que même le micro-gestionnaire le plus dur reconnaît qu'il est au-dessus de leur tête à ce niveau. Mais le génie de votre patron peut trouver un moyen de briser le rideau de silicium.
Et, en prime, cela gaspille énormément de temps de développeur à faire la traduction, même avant il utilise la traduction anglaise pour commencer à suggérer diverses améliorations (je suppose qu'il sait comment coder mieux que les programmeurs , même s'il ne peut pas lire le code, et pourra partager sa sagesse dès que quelqu'un le traduira, sinon pourquoi aurait-il besoin chaque ligne traduite?).
Donc, non, ce n'est pas une demande raisonnable, et je n'en ai jamais entendu parler auparavant. Et je ressens pour toi. Je pense que tout le monde peut avoir besoin de commencer tranquillement à 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, vous pouvez peut-être obtenir un nouvel anti-modèle nommé d'après votre situation? Que diriez-vous de l'anti-modèle "Dirty Hungarian Phrasebook", après le sketch Monty Python où un buraliste essaie de communiquer avec quelqu'un qui ne parle pas anglais en utilisant un livre de phrases hongrois qui a comiquement fausses traductions?
Asseyez-vous avec lui et parlez-lui de 10 lignes du code. Expliquez chaque détail jusqu'à ce que vous conveniez tous les deux qu'il le comprend autant qu'il le voulait.
Peut-être que cette expérience est tout ce qu'il recherche: juste une impression de ce à quoi ressemble votre travail pour vous, et à quoi ressemble le 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: remarquez combien de questions 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 omettre? Combien de temps aurait-il fallu avant que les résultats ne 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. LE CODE SOURCE n'est pas destiné à être lu en anglais (ou dans toute autre langue d'ailleurs).
Il a peut-être peur que vous fassiez faire à votre code quelque chose qu'il n'approuve pas ou dont il n'a pas conscience. Si tel est le cas, je ne pense pas que vous puissiez y remédier. Vous devrez rédiger la documentation ou peut-être le convaincre d'embaucher quelqu'un pour auditer 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 manager ne devrait pas raisonnablement s'attendre à être en mesure de bien comprendre ce que vous faites
J'ai eu une expérience similaire à cela dans un emploi précédent. Mon manager était un comptable (et donc très orienté vers les détails) et ne comprenait pas ou ne faisait pas vraiment confiance à la programmation. Elle ne pouvait pas comprendre qu'elle, en tant que personne non technique, ne devrait pas s'attendre à pouvoir 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 sur la manière de gérer et de modifier le code (oui, vraiment), j'ai cessé d'essayer de la distraire, et j'ai carrément refusé. L'analogie que j'expliquais était simple:
- Je ne suis pas comptable
- Je ne devrais pas m'attendre à comprendre chaque transaction ou publication dans nos comptes
- Cela ne veut pas dire que les comptes sont faux ou non fiables, simplement parce que je ne les comprends pas
- Ceci est rendu possible par confiance la personne qui les a compilés
Au bout du compte, voici à quoi cela ressemble pour moi: un manager 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. C'est votre travail de comprendre le code et de permettre à quelqu'un avec des compétences similaires aux vôtres de le comprendre, pas à celui de votre manager. Leur montrer ce fil peut être une bonne idée (ou vraiment, vraiment terrible, selon leur personnalité).
Ligne par ligne, c'est ridicule. Ce que je pourrais suggérer, c'est de proposer de générer des documents à partir des commentaires et de lui donner cela. C'était suffisant pour un certain nombre de subventions et de vérifications du gouvernement canadien sur lesquelles j'ai travaillé par le passé.
Il n'obtiendra pas ligne par ligne mais il obtiendra méthode par méthode qui devrait toujours être plus granularité qu'il n'en a besoin.
Quelques solutions existantes, selon votre plateforme:
- 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 du code que de traduire l'intégralité du code d'une application intéressante en anglais. De plus, nous avons essayé cela avec COBOL et cela n'a pas aidé du tout. S'il ne veut pas apprendre, mais veut simplement faire de son ignorance le problème de quelqu'un d'autre, vous avez un patron à la tête très pointue.
Utilisez votre expertise technique pour poursuivre votre patron.
- Faites-lui savoir qu'il vous faudra autant de temps pour le faire que pour le coder en premier lieu (n'hésitez pas à le prolonger.).
- Demandez-lui à quel point ce document doit être à jour. Informez-le que toutes les modifications de codage prendront au moins deux fois plus de temps.
- 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 du pseudo. 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. Peut-être que votre patron est confronté à des questions techniques par la haute direction et qu'il se sent gêné car il est incapable de répondre. Il pourrait y avoir une section particulière du code qui le préoccupe le plus, vous pouvez donc limiter cette entreprise massive à ce seul domaine.
En soumettant un échantillon, il peut arriver à 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?), Peu importe la langue dans laquelle elle se trouve. Il vaut mieux de comprendre l'application du point de vue de l'utilisateur expérimenté. Je pense qu'il est juste pour vous de lui faire savoir que vous préférez écrire du vrai code/indice - je cherche un autre travail.
Pourquoi?
Un commentaire ligne par ligne 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 puisse reprendre le projet si je pars?
- tu veux voir que je fais du vrai travail?
Il peut y avoir un désir raisonnable derrière cette demande, et vous pourrez peut-être faire plaisir à votre patron en le comprenant et en répondant à ce besoin.
Mise à jour
Basé sur Mikey's commentaire, je l'ai peut-être dit un peu trop brutalement. Je ne veux pas dire que vous devriez littéralement dire "pourquoi voulez-vous cela?", Juste cela 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 pensé à 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 peut-être quelque chose que je ne vous communiquais pas bien à propos de mon travail. Qu'est-ce que vous voulez vraiment comprendre sur notre code, ou sur ce que je fais? Qu'est-ce que vous essayez d'accomplir ici? "
Bien sûr, c'est possible que votre patron est totalement déraisonnable. Mais il est plus probable qu'il ne sache pas à quel point cette demande est étrange et qu'il a un objectif rationnel en tête.
Sinon, commencez à peaufiner votre CV. :)
Même une traduction ligne par ligne ne transmettra pas efficacement la signification de chaque ligne de code. Une compréhension des programmeurs d'une ligne de code est toujours dans le contexte de nombreux facteurs. Entrez dans quelque chose comme un morceau de code multi-thread et la traduction en anglais n'aura pas plus de sens que le code brut. Pensez aux fonctionnalités réparties entre plusieurs fonctions/fichiers. Un certain code n'a absolument aucun sens sans expliquer de grandes quantités 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. À peu près tout ce qui va au-delà du code procédural de la fonction divine nécessitera une grande quantité de connaissances en programmation juste pour comprendre la traduction anglaise. Regardez également quelque chose d'aussi simple qu'une déclaration de décision if/else. Il n'y a pas de ligne par ligne, car la ligne suivante dépend des données d'exécution. La ligne suivante pourrait être l'une des nombreuses possibilités. Au moment où vous aurez expliqué ce que fait votre application, vous aurez fait de votre PM un programmeur et vous aurez tous les deux 5 ans de plus.
Depuis que j'enseignais la programmation, je ne serais que trop heureux de l'essayer.
Il découvrira rapidement qu'il obtient plus que ce qu'il avait négocié, ce qui me rendra triste parce que je comme expliquant les choses : -)
Quand vous parlez de votre "patron", est-ce "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 qui est responsable, PARLEZ À SON BOSS, faites remarquer que pour répondre aux exigences de votre patron, votre productivité pour l'entreprise sera réduite au 1/3 de ce qu'elle pourrait être.
SI votre patron est "le gars qui signe les chèques", expliquez-lui la même chose, juste plus diplomatiquement. Votre travail est passé de "Écrire le code" à "Écrire le code, écrire l'explication du code, expliquer l'explication".
Cela ressemble à une bonne chance d'essayer la programmation alphabétisée. Recherche le sur Google. :)
Mais ... ce n'est pas nécessairement une demande entièrement déraisonnable. Une partie de votre travail (la partie la plus importante, imo) consiste à communiquer votre ou vos algorithmes à d'autres développeurs et, si nécessaire, à des personnes non techniques. Les programmeurs de génie solitaires qui ne peuvent pas communiquer sont toujours problématiques, je pense.
À cette fin, votre code doit être clairement clair (ce qui signifie: soit vraiment auto-documenté ou bien documenté, et par "auto-documentation", je veux dire que les variables et les fonctions ont n sens ou responsabilité et leurs noms reflètent clairement). Votre patron peut avoir de bonnes raisons pour sa demande. Peut-être (je devine juste ici) vous ou votre prédécesseur avez la réputation d'un code impénétrable et fragile et c'est le remède de votre patron. C'est un peu extrême, mais cela pourrait être un exercice utile pour vous. Je suppose qu'il sait qu'il faut du temps pour écrire de meilleurs documents (et s'il ne le fait pas, il devrait être éduqué - c'est comme écrire un article de terminologie: il faut plus de temps pour écrire que pour lire).
Un organigramme lui sera probablement plus avantageux. C'est certainement une demande inhabituelle et ne dit pas grand-chose de lui en tant que manager.
Le fait que votre patron soit disposé à passer du temps à comprendre le code que vous avez écrit, vous pouvez l'utiliser à votre avantage. Essayez de lui présenter Cucumber: http://cukes.info/
et incitez votre patron à écrire le test BDD pour vous à l'avenir.
La beauté de l'anglais est qu'elle est magnifiquement obfucée. Si vous utilisez cela à votre avantage, vous n'aurez peut-être plus jamais à traiter ce type de demande. Je prendrais un petit morceau de code comme exemple mais qui est très abstrait et pas du tout facile à comprendre. Je rédigerais alors les commentaires en anglais technique comme si vous l'écriviez pour un chapitre dans un livre de programmation. Plus c'est 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/10e 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. Quand 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 faire ce niveau de documentation, il reculera assez rapidement. Mais essayez très sérieusement d'accomplir sa tâche. N'essayez pas ceci si vous ne pouvez pas retirer cela et il soupçonne que vous le jouez.
Cela ressemble à un candidat pour un patron aux cheveux pointus spécial numéro de vacances Dilbert bande! Sa demande ne semble certainement pas raisonnable à première vue.
Humour mis à part, essayez de savoir ce dont il a vraiment besoin , et pourquoi, puis dites-lui ce qu'il lui en coûtera en dollars ou en heures pour lui donner cela, et le laisser décider s'il veut dépenser autant d'argent là-dessus.
Quant à vous, comptez les heures qu'il vous faudra pour répondre à sa demande apparemment bizarre, puis déterminez si vous ne feriez pas mieux d'investir une fraction de ce temps dans la recherche d'un nouvel emploi pour un employeur prêt à vous traiter. en tant que professionnel!
Amenez-le dans votre bureau et faites-lui visiter votre code.
Il réalisera à mi-chemin qu'il a fait une demande absurde, et il s'éloignera et ne vous dérangera plus jamais.
Si vous ne cédez pas à ses demandes pour l'aider à comprendre votre code, il trouvera des moyens différents mais tout aussi absurdes de vous pousser.
C'est un cas où l'apaisement fonctionne mieux que l'abrasion.
Ce serait très bien si nous avions un traducteur "Language X to English" qui le ferait. Ensuite, on pourrait sourire et dire, pas de problème, patron, vous aurez ça dans une minute. Et puis vient un mail avec quelques mégaoctets de texte qui lit:
- Soit a un nouveau tableau entier avec 20 éléments.
- Soit x une variable pour stocker des entiers.
- Réglez x sur 0
- Alors que x est inférieur à 20, faites ce qui est prescrit dans les 2 lignes suivantes
- définissez 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 suggérer désormais la programmation en Shakespeare .
Il ne devrait pas se soucier de savoir quoi que ce soit. Dites-lui que la mise en œuvre du développement logiciel est susceptible de changer. La conception de l'événement peut changer. Parlez-lui des informations qui se cachent, de l'encapsulation et de l'abstraction.
Lui, en tant que membre de votre équipe, en tant que client de votre code, au sens large, ne devrait travailler qu'avec 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 de code de quelqu'un d'autre. En savoir plus, ne fera que le ralentir et le risque de faire des hypothèses basées sur le fonctionnement interne de votre code. Ces hypothèses cesseront de tenir, lorsque vous devrez changer votre code, ce qui devient un problème, s'il a construit tout type de système ou de processus basé sur elles.
Et aussi avoir à faire ce genre de travail réduira votre efficacité. Non seulement vous devrez apporter des modifications ultérieures à deux endroits différents, mais cela aura également un impact négatif sur votre moral au travail, ce qui réduira encore plus votre rendement.
Mon patron veut une explication narrée ligne par ligne de notre code
Dure.
Comme il n'est pas programmeur, il ne peut pas suivre le code, il veut donc tout traduire 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.
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 dont vous disposez, parcourez votre AST générant des descriptions basées sur des modèles pour chaque nœud, donc i++ est décrit comme increase i by 1 using postfix increment operator. Ça devrait être vraiment drôle. Votre patron peut également souhaiter que cet outil soit inclus dans le script de génération, donc chaque fois que vous apportez des modifications, il recevra un e-mail de ~ 20 Mo décrivant ce que fait la nouvelle version.
P.S. Je plaisante, c'est un idiot.
En tant que programmeur, vous avez vraiment "deux" tâches.
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'un autre côté, il vous fait travailler plus dur sur votre "deuxième" travail.
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 devrait être à votre avantage à long terme, lorsque vous lui demandez plus de matériel, de personnel ou d'argent pour des augmentations. Après tout, il vous a demandé de faire plus de travail.
Je pense que BDD conviendrait bien à ce problème, bien qu'il semble que votre projet soit presque terminé, donc un peu difficile à implémenter maintenant, donc c'est plus comme pour 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.
Vous pouvez écrire des tests d'acceptation en utilisant un cadre de conception axé sur le comportement tel que 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 testeur sera rouge.
Découvrez la vidéo d'introduction. C'est peut-être une bonne diversion pendant que vous trouvez un nouveau patron ... ;-)
Bien que je convienne qu'il s'agit d'une demande déraisonnable, votre patron peut apprécier quelque chose comme la sortie de Docco , qui sépare votre code et vos commentaires ligne par ligne ou clause par clause en HTML à deux colonnes sortie, avec le code d'un côté et la 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, ne section commentée ligne par 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 est en fait une personne raisonnable. Si c'est le cas, raisonner avec lui/elle pourrait fonctionner - une conversation informelle où vous promettez de fournir "ce qu'il veut vraiment", c'est-à-dire; un guide en prose de ce que fait le programme.
S'il s'agit de "mon chemin ou l'autoroute", vérifiez mieux votre essence maintenant.
Votre manager est presque certainement affligé par le fait qu'il ne comprend pas ce que font les gens qu'il gère, et il n'a pas les antécédents pour comprendre les résultats qu'ils produisent.
Je doute qu'il ait réfléchi très attentivement à cette solution, et cela lui a probablement paru raisonnable à première vue. Mais c'est en grande partie parce qu'il ne comprend pas ce qu'est réellement le code de programmation.
Tout programmeur comprend l'absurdité de cette demande, 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 également 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, bien que 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-le à quelqu'un qui ne comprend que les ventes, et il sera tout aussi confus après avoir lu les commentaires qu'avant.
Vous pourriez réellement 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 sont assez compactes en termes de syntaxe, 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 passe, et plus important encore pourquoi il ne veut pas lire votre code.
Demandez-leur pourquoi ou quelle est leur motivation pour la demande, puis déterminez honnêtement les coûts impliqués et partagez-les avec le demandeur. S'il s'agit d'une demande déraisonnable et peut-être malveillante, recherchez un autre emploi.
Tout d'abord, demandez quel est l'objectif ici. Trouvez d'autres façons d'accomplir toute explication qu'il a.
Ensuite, fournissez une estimation du temps que cela prendrait, à la fois en termes de combien d'heures il faudrait pour assembler et combien de temps cela prendrait pour fonctionner. Demandez, en termes délicats, si vous ne passez pas votre temps à faire autre chose à la place.
Commencez par lui indiquer le nombre de milliers de lignes de code de votre application.
Si cela échoue, comme déjà suggéré, fournissez un échantillon de ce à quoi il doit s'attendre lorsque vous racontez tout le code avec lui. Cela devrait le satisfaire.
S'il persiste, commencez à chercher un nouvel emploi.
BTW, c'est vraiment un cas où le chef de projet doit intervenir et expliquer au patron que ce niveau de détail n'est pas dans l'intérêt de tous.
Ce n'est pas une idée irrationnelle et tout à fait logique. Il est de son devoir de vérifier le code et de voir s'il y a quelque chose à casser.
Maintenant, c'est à vous de décider ce que vous pouvez faire de votre mieux pour le rendre simple. Comme quelqu'un l'a déjà suggéré, faire un bon document de conception avec de simples diagrammes UML peut être le meilleur moyen. Il n'est pas toujours nécessaire de commenter ligne par ligne. En tant qu'utilisateur final (ou client), quelqu'un peut faire une demande, maintenant c'est à vous de voir comment vous la remplissez (création de documents de conception ou de l'utilisateur final ou rédaction de commentaires ligne par ligne).
Même dans mon travail, quand j'ai rejoint une nouvelle entreprise, on m'a dit de le faire par mon chef. Lorsque vous êtes nouveau dans un endroit, vous avez besoin de temps pour bâtir votre réputation, et à ce moment-là, de telles demandes arrivent. Je l'ai rempli, en créant des diagrammes UML modulably.
Faire une explication ligne par ligne augmentera certainement la taille de votre fichier de codage, c'est la raison pour laquelle introduire la documentation séparément.
Quoi qu'il en soit, s'il veut une explication ligne par ligne beaucoup plus détaillée, il suffit de joindre la documentation du langage de programmation dans lequel vous avez codé et lui demander de s'y référer (par exemple, si vous codez en Java puis référez-vous à JavaTM 2 Platform, Standard Edition, v 1.4.2 API Specification).
Cela fonctionnera certainement. :-)
Code [[# # ~] est [~ # ~] anglais déjà, 'pour', 'si', 'autre', etc. Effectuez simplement une recherche et remplacez certains caractères. Par exemple, remplacez ">" par "supérieur à".
"Bien sûr pas de problème"
Commencez à la première ligne de votre application JavaScript, <!DOCTYPE html>
Et descendez jusqu'à l'électronique du CPU ...
Faites cela pour chaque octet de code.
Expliquez ce qu'est le doctype, expliquez le prupose, expliquez l'histoire, expliquez les alternatives.
Problème?
À mon humble avis, s'il est responsable de l'accomplissement de la tâche, il devrait savoir comment cela fonctionne ... :)
Je dirais simplement que vous êtes plus que disposé à le faire, mais cela vous prendra x semaines pour terminer et est-il sûr qu'il veut/a besoin de vous pour le faire?
Il réalisera sûrement que votre temps serait mieux dépensé ailleurs?
Je crée des explications "en anglais" pour presque toutes les autres lignes de mon code - dans les commentaires de code. Je ne vois pas cela comme un fardeau déraisonnable. Certes, comme vous le décrivez, cela semble un peu louche. Quelque chose de plus que cela est un drapeau rouge que vous pourriez avoir un patron déraisonnable ou qu'il y a un problème avec votre relation de travail.
Nous avons tous eu des gestionnaires à un moment ou à un autre qui veulent quelque chose de ridicule comme ça. Il est difficile de ne pas partir à moitié armé, mais il est important que vous ne le fassiez pas - il va juste creuser. Peut-être que vous pouvez lui faire une liste des avantages et des inconvénients et les parcourir avec lui. À mon avis, le premier élément du côté con est un bon code qui s'auto-documente. Mais ils ne tombent presque jamais pour ça.
C'est peut-être une chose stupide à en fait faire, mais pourriez-vous mettre en place un compilateur qui compile les langues que vous utilisez en anglais "prose"? Vous pouvez exécuter votre code via le compilateur, utiliser quelque chose comme wc pour déterminer le nombre de lignes qu'il contient, puis le mettre à la disposition de votre patron (peut-être menaçant de l'imprimer;).
Je dirais que lui montrer cette question et toutes les réponses que vous avez, l'aiderait à comprendre qu'il est déraisonnable! Essayez donc de lui demander de voir toutes les réponses ici, mais bien sûr de manière non offensive et respectueuse. Il comprendra le fonctionnement des développeurs!
De plus, je dirais essayer d'utiliser des diagrammes, comme beaucoup de personnes déjà mentionnées. Mais encore une fois, pensez sérieusement à lui montrer les réponses données ici!
Vous devez d'abord établir l'étendue de la demande. Vous devez vous assurer que vous ne rendez pas le boss-under-the-desk plus effrayant que le monstre.
Est-ce plus: // La méthode obtient un client. Ou plus: // Une longue explication détaillée de la programmation comprenant ce qu'est un int, ce que veut dire "void", et inclut les mathématiques réécrites en concepts anglais?
C'est probablement quelque part entre les deux.
S'il s'avère que la demande est trop extrême:
Je vous suggère d'expliquer à votre patron que même si cela semble être une petite chose, les programmeurs ne sont pas formés à l'une ou l'autre chose ou ne s'expriment pas de cette manière, sauf dans le sens le plus général du code. Il y a des gens qui sont formés pour transmettre des idées complexes aux laïcs, on les appelle des rédacteurs techniques.
Je pense qu'un problème n'a pas été bien réglé, ou pas du tout. Pour ce faire, cela doit être fait lors de l'écriture du code. Sait-il combien de temps cela prendra en essayant de respecter les délais?
Étant donné que ces types de commentaires ne devraient pas figurer dans le code, il n'existe aucun bon moyen ni outil (à ma connaissance) pour faire fonctionner cela.
C'est un cauchemar de maintenance. Même si une méthode est trouvée pour retirer cela lors de la génération de code, une fois que le code entre en maintenance, comment les commentaires seraient-ils conservés?
Si après un chat, si vous pensez que votre patron ne comprend toujours pas, commencez à chercher de nouveaux emplois. La personne qui n'a qu'une seule idée folle de chauve-souris est plus rare qu'une licorne.
Et si cette personne ouvre des fichiers de code, j'espère que vous disposez d'un très bon contrôle des sources.
Idéalement, chaque code devrait être lisible et compréhensible pour vos collègues ou votre patron. Si votre patron le veut, votre code n'est pas assez expressif, il ne communique pas assez bien votre intention. Ne racontez pas votre code, écrivez votre code pour qu'il ressemble autant que possible à une narration anglaise! Voir Langages spécifiques au domaine (DSL) pour plus de détails.
Quelques liens:
Je voudrais juste lui montrer la vidéo Tri rapide avec la danse folklorique hongroise (Küküllőmenti legényes) puis lui expliquer combien de temps il faudrait pour cela toutes les lignes de code dont vous disposez.
C'est une demande très déraisonnable. Vous êtes engagé pour écrire du code et un programme, et toute documentation que vous écrivez est censée aider d'autres développeurs ou programmeurs travaillant sur le même projet - pas votre patron ou employé.
Euh ...
Avez-vous construit votre code à partir d'une spécification? L'exigence était-elle correctement documentée?
S'il est un manager à moitié décent, il devrait demander "Est-ce que cela répond aux exigences?"
Si vous avez dit oui à ce qui précède ... donnez-lui ces documents + les choses que vous avez déjà mentionnées, s'il en veut toujours plus, il est idiot et ne devrait clairement pas gérer une équipe de développement.
Et avant que cet imbécile revienne avec "bien ce que nous savons" ... je parie qu'il y a au moins 50 ans d'expérience combinée dans ce seul fil.
Rôle d'un manager: 1. Identifier et assigner des objectifs. 2. Assurez-vous qu'ils sont correctement exécutés. 3. Ne posez pas de questions stupides auxquelles il faudrait déjà répondre.
Franchement, si vous avez déjà une solution, il devrait savoir ce qui a été écrit. S'il n'a aucune idée de ce que vous faites, je suppose que quelqu'un au-dessus de lui a demandé des détails sur ce que son équipe faisait.
Vous pourriez être vraiment intelligent et relier votre solution au plan d'affaires et montrer où vous atteignez les objectifs principaux de l'entreprise, puis transmettre les détails à son supérieur hiérarchique en déclarant que votre propre gestionnaire ne semble pas capable de vous comprendre.
Vous obtiendrez probablement son travail.
On m'a spécifiquement demandé de donner ligne par ligne (ou le cas échéant - par exemple image par image, etc.) une explication/un commentaire que mon patron souhaite pouvoir lire et suivre.
Donnez-lui un organigramme lol ...
Soit cela, soit il demande une documentation utilisateur?
Je voudrais également signaler à votre patron que cela prendrait X heures de votre temps. après avoir vu ce que cela prendra, je serais surpris s'il vous demande de continuer.
Je l'inviterais également à passer en revue le code de votre fonctionnalité. Non pas pour qu'il puisse comprendre quoi que ce soit, mais simplement pour comprendre que c'est ce que vous et votre équipe faites en interne pour NE PAS avoir à verbaliser votre code. Si votre patron vous le demande, mon instinct me dit qu'il/elle ne fait pas confiance à votre équipe ou ne fait pas preuve de diligence raisonnable. En le laissant passer un examen du code, cela démontrerait la diligence raisonnable et il/elle vous laisserait, espérons-le, tranquille.
Oui, je suis d'accord que ce n'est pas une demande raisonnable pour nous, mais peut-être qu'il est curieux de savoir comment tout cela fonctionne. Donc, pour un non-programmeur, je dirais utiliser organigramme . Pour que votre patron puisse voir la situation dans son ensemble ou vous pouvez également entrer autant de détails que vous le souhaitez dans les organigrammes selon ses besoins. Il existe de nombreuses applications de diagramme de flux disponibles. J'ai trouvé Balsamiq Mockups utile. J'espère que ça aide.
Une image vaut mille mots. Dessinez Use Case et Sequence diagrammes. Ils doivent être suffisants pour expliquer le but/le flux du logiciel.
P.S: Quoi que vous fassiez, évitez de bourrer votre source de commentaires. Cela ajoutera un gonflement surtout s'il est stocké dans un système de version. Ajoutez plutôt des nombres/codes qui se réfèrent aux schémas suggérés.
Vous pouvez également suggérer de passer à Literate Programming et COBOL ou FORTRAN depuis https://stackoverflow.com/questions/152160/using-noweb-on-a-large-Java-project ou simplement demander pourquoi il n'exige pas que chaque graphiste explique chaque utilisation d'un outil qu'il fabrique.
Vous êtes un spécialiste, vous êtes censé livrer un produit haut de gamme, sans expliquer en détail que vous peignez un trait verdâtre ici, puis appliquez un flou gaussien de 2 pixels, etc.