我的老板希望对我们的代码进行逐行叙述的英语解释

我被特别要求我逐行（或适当地-例如逐个图像等）给出我的老板希望能够阅读和遵循的解释或评论。

由于他不是程序员，所以他无法遵循代码，因此希望将其全部翻译成英文。

有人被要求这样做吗？

我已经对所有源代码进行了评论，并使用JSDoc生成了所有函数，变量等的完整文档，并包括一个实现示例和完整的带有演示的演示程序。

我还能为非程序员注释代码吗？

这不是一个合理的要求，对吗？

更新

最后，我设法解释了为什么没有充分利用时间来完成他的要求。他是一个理性的人，只是对我的工作不了解。一旦他看到了这个帖子，我想他很快就会明白这不是正常的要求。

我确实提供了适合其他程序员遵循的文档（JSDoc和内联注释-以及有关技术问题的一些附加说明），以及该程序主要逻辑的非常宽泛的流程图，供老板参考。

最后，各方都感到满意，我们继续前进。

不，这不是合理的要求！

一定要从中说出自己的想法，或者让别人从中说出他的想法。这是一个不合理的想法，尽管可行的方法成本很高，但实际上不应该这样做。对功能和子例程的概述是合理的，但要“解释”每条代码行则不合理。对他而言，学习阅读手语比这样做更为有效。

他接下来要问的是将数学公式转换成英文文本。尽管肯定有可能带来很多错误和误解的余地，但绝对不要这样做。就像将代码“翻译”成英文一样。

你有设计文件吗？这些是该代码的英文解释。非编程经理应该不需要更多。

是否有年度最佳微型经理奖？听起来你的老板值得提名。认为自己需要逐行理解代码但又不想学习如何直接阅读代码的人，可以像想象中的那样完美。

成为开发人员的一个优势是，理解代码的困难至少在非技术管理方面至少在详细的实现级别上至少在某种程度上阻止了微管理，因为即使是最核心的微管理者也意识到它们是在他们的头上。但是老板的天才也许找到了打破硅幕的方法。

而且，作为奖励，即使在他使用英语翻译开始提出各种改进建议之前，它也浪费了大量开发人员的时间（我假设他比程序员更懂编码，尽管他不能阅读代码，只要有人翻译，就能分享他的智慧，否则他为什么需要翻译每一行？）。

所以，不，这不是一个合理的要求，而且我之前从未听说过。我为你感到。我认为每个人都可能需要静静地寻找另一份工作，因为一旦他开始使用代码转换作为管理工具，它可能将成为一个残酷的工作场所（或更糟糕的工作场所）。

从好的方面来说，也许您可​​以根据自己的情况命名一个新的反模式？在蒙蒂Python断言之后，吸烟者试图通过使用带有可笑的错误翻译的匈牙利短语集来与不会说英语的人交流，“反匈牙利短语集”反模式如何？

和他坐下，通过10行代码与他交谈。解释每个细节，直到你们俩都同意他理解他想要的程度为止。

也许正是他所追求的就是这种体验：只是对您的工作印象以及从您的角度看该软件的印象。在我的书里那是一件好事。

如果之后，他仍然希望您继续说，请注意：我必须问多少个问题；想象一下，如果我不得不在无法提出问题的情况下解释所有这些问题，那么我怎么可能知道要包括的内容和要忽略的内容呢？结果将花费多少时间对您有用？现在您要我用这种方式做几行？

我认为这不是一个合理的要求。源代码无意以英语（或与此相关的任何其他语言）阅读。

也许他担心您将使您的代码执行他不赞成或不知道的事情。如果是这样，我认为您无法为此做任何事情。您将不得不编写文档，或者说服他/她雇用某人来审核您的代码。

真的很简单：

• 由于您是一名程序员而被录用了
• 您的经理没有这些技能
• 因此，您的经理不应合理地期望能够完全了解您的工作

在上一份工作中，我也有类似的经历。我的经理是一名会计师（因此非常注重底层细节），并且不理解或不真正信任编程。她无法理解，作为一个非技术人员，她不应该期望能够掌握我所写内容的细节。在多次索要过多文档并要求培训非技术用户如何管理和更改代码的请求之后（是的，真的），我停止试图欺骗她，并彻底拒绝了。我用来解释的类比很简单：

• 我不是会计师
• 我不应该期望了解每笔交易或我们帐户中的过帐
• 这并不意味着这些帐户是错误的或不可信的，仅仅是因为我不理解它们
• 这可以通过信任编译它们的人来实现

总而言之，这就是我的感觉：一个难以信任员工的经理；或担心他们会离开，并认为这是缓解这种情况的有效方法。

唯一的解决方案是坐下并解释为什么这没有意义。这是你的工作是理解代码，并有可能使一个人有类似的技能集到你了解它，而不是你的经理。向他们显示此线程可能是一个好主意（或者，根据他们的性格，这确实是一个非常可怕的主意）。

逐行，很荒谬。我可能建议提供从注释生成文档并将其提供给他的方法。这足以应付我过去从事的许多加拿大政府拨款和审计工作。

他不会得到行由行，但他会得到方法，通过法应该仍然是更多的粒度比他的需要。

现有的一些解决方案，具体取决于您的平台：

• C＃：沙堡
• Java的：的javadoc
• “ C ++，C，Java，Objective-C，Python，IDL（Corba和Microsoft风格），Fortran，VHDL，PHP，C＃，并在某种程度上是D。” ：氧气

对于他而言，学习阅读代码要比将任何有趣的应用程序的整个代码翻译成英语要快得多。此外，我们使用COBOL进行了尝试，但完全没有帮助。如果他不愿意学习，而只是想让他的愚昧无知别人的问题，那么你就是一个认真的尖头老板。

利用您的技术专长追求老板。

1. 让他知道执行此操作所需的时间与最初为您编写代码所需的时间一样长（请随意使其更长。）
2. 问他该文件需要最新信息。通知他所有编码更改现在至少需要两倍的时间。
3. 如果您或任何其他人发现任何错误，请问他是否应该立即修复或等待完成伪编码。提醒他有关＃1和＃2的信息。

像所有糟糕的解决方案建议一样，最好找出问题所在。也许您的老板因高层管理人员遇到了技术问题，并且因为无法回答而感到尴尬。他可能最关心的是代码的特定部分，因此您可以将这一繁重的工作限制在该区域。

通过提交样本，他可能得出结论，如果您不了解编码的工作方式（什么是循环以及对所有这些项目的作用是什么？），与所使用的语言无关紧要。从超级用户的角度了解应用程序。我认为让您知道他愿意编写真实的代码/提示对您来说很公平-我正在寻找另一份工作。

为什么？

逐行注释是不合理的，但这是我要问的：您为什么要这样做？

是因为...

• 您想全面了解该软件的功能（不一定要怎么做）？
• 您想确定如果我离开，另一个程序员可以接这个项目吗？
• 您想看到我在做真实的工作吗？

这个请求背后可能有一个合理的愿望，您也许可以通过弄清并满足需求来使老板满意。

更新资料

根据Mikey's评论，也许我直言不讳。我并不是说您应该从字面上说“为什么要这么做？”，而只是您应该找出答案。措辞和语气有很大的不同。具体来说，您可以这样说：

“我一直在考虑您要求对每一行代码进行解释。以这种方式做事有点不寻常。我想知道也许我在工作方面没有和您很好地沟通。您真正想了解我们的代码或我在做什么的事情是什么？您想在这里完成什么？”

当然，您的老板很可能完全不合理。但是他更有可能不知道这个要求有多奇怪，并且有一些合理的目标。

如果没有，请开始完善您的简历。:)

听起来是尝试识字编程的好机会。谷歌一下。:)

但是...这不一定是完全不合理的要求。您的工作（更重要的部分是imo）是您与其他开发人员以及（如有必要）非技术人员进行算法交流的一部分。我认为，无法沟通的孤独的天才程序员总是有问题的。

为此，您的代码应清晰明了（意思是：真正地自我记录或充分记录，并且通过“自我记录”，我的意思是变量和函数具有一种含义或责任，并且其名称清楚地反映了这一点）。您的老板可能有充分的理由要求他。也许（我只是在这里猜测）您或您的前任以坚不可摧，脆弱的代码而闻名，这是老板的补救措施。这有点极端，但可能对您有用。我假设他知道写更好的文档需要时间（如果他不写，就应该教育他-就像写学期论文：写比阅读要花更长的时间）。

即使逐行翻译也无法有效传达每行代码的含义。程序员对一行代码的理解始终是在许多因素的背景下进行的。进入一段多线程代码后，英文翻译将比原始代码没有任何意义。考虑一下分散在多个功能/文件之间的功能。如果不解释大量其他代码，则某些代码绝对毫无意义。尝试逐行解释依赖注入所涉及的不同部分，您将明白我的意思。几乎所有超出上帝功能的程序代码的内容都需要大量的编程知识才能理解英语翻译。另外，看一下if / else决策语句一样简单的内容。没有逐行 因为下一行取决于运行时数据。下一行可能是几种可能性之一。在您解释了应用程序的功能时，您将使PM成为程序员，并且两者都将比您大5岁。

由于我曾经教过编程，所以我很乐意尝试一下。

他会很快发现自己的收益超出了他的讨价还价，这会让我很难过，因为我喜欢解释事情:-)

当您提到“老板”时，这是“负责您/您的团队的中层经理”吗？还是公司的所有者？您是“按小时”支付还是“按薪水支付”？

如果您的老板是负责任的中层经理，请与他的老板说一声，指出要满足老板的要求，您公司的生产率将降低到原来的1/3。

如果您的老板是“签支票的人”，可以用外交手段向他解释同样的事情。您的工作已从“编写代码”变为“编写代码，编写代码说明，解释说明”。

流程图可能会给他带来更多好处。当然，这是一个不寻常的请求，对于他作为经理的说法并没有多说。

您的老板愿意花一些时间来理解您编写的代码这一事实，您可以从中受益。尝试向他介绍黄瓜：http : //cukes.info/

并让您的老板在将来为您编写BDD测试。

他不应该不知道这些。告诉他，在软件开发中实现可能会发生变化。活动设计如有变更，恕不另行通知。告诉他有关信息隐藏，封装和抽象的信息。
从广义上讲，他是您团队的一部分，也是代码的客户，应仅对代码的用途进行清晰，高级的抽象。您的代码的任何层与其他人的代码的另一层使用相同的方式。仅此而已，只会让他放慢脚步，并冒着使他冒犯基于代码内部工作原理进行假设的风险。如果他必须基于这些代码构建任何类型的系统或流程，那么当您不得不更改代码时，这些假设将不再成立。
而且必须执行此类工作会降低您的效率。您不仅需要在两个不同的地方进行后续更改，而且还会对您的工作士气产生负面影响，从而进一步降低您的工作量。

英语的美是混淆的优美。如果您利用它来发挥自己的优势，那么您可能再也不必处理这种请求了。我将一小段代码作为示例，但其中的代码非常抽象，一点也不容易理解。然后，我将用技术英语来编写注释，就好像您是为编程书籍中的一章编写注释一样。遵循时间越长，越复杂越好。告诉他，您记录此功能花了多少小时。然后解释一下，它仅是实际代码库的1％的1/10（如果可能，请使用基于代码行的实际数据，它们可能比这还差）。当他意识到自己不知道英文翻译怎么说时，并且需要20,000个工时才能完成此级别的文档编制时，他将很快退后一步。但是要非常认真地尝试完成他的任务。如果您无法做到这一点，请不要尝试，他怀疑您在玩他。

这看起来像是假日发行的尖头上司迪尔伯特脱衣舞的特别候选人！乍一看，他的要求当然听起来不合理。

除了幽默之外，尝试找出他的真正需求以及原因，然后告诉他要给他多少钱或数小时，然后让他决定是否要花那么多钱。

至于你自己，计算出你要满足他看似奇怪的要求所花费的时间，然后确定你是否会花费那部分时间来寻找一份愿意为你服务的雇主的新工作呢？作为专业！

带他到您的办公室，并带他参观您的代码。

他会在某种程度上意识到自己提出了荒唐的要求，并且他会走开，再也不会打扰您了。

如果您不肯要求他帮助他理解您的代码，那么他会找到其他但同样荒唐的方式来嘲笑您。

在这种情况下，app靖胜于磨擦。

如果我们有一个翻译员“ Language X to English”来做到这一点，那就太好了。然后一个人可以笑着说，没问题，老板，一分钟之内就可以解决。然后是一封带有几兆字节文本的邮件，内容为：

• 设a为一个包含20个元素的新整数数组。
• 令x为存储整数的变量。
• 将x设为0
• 当x小于20时，请执行以下两行中的规定
• 将索引为x的a的数组元素设置为使用参数x + 1调用nThPrime的结果
• x增加1
• ....

另一个选择是建议以后在莎士比亚编程。

我的老板希望对我们的代码进行逐行叙述的英语解释

强硬。

由于他不是程序员，所以他无法遵循代码，因此希望将其全部翻译成英文。

如果他不是程序员，则不应阅读代码。完全没有

而是提供高级文档。

这不是一个合理的要求，对吗？

没有。

作为程序员，您确实有“两个”工作。

首先是创建好的程序。第二种是将其“出售”给公司内部和外部的客户。

您老板的要求“伤害”了您的第一份工作。需要更多时间来记录您的程序。另一方面，他实际上使您在“第二”工作上更加努力。

您的老板要您用英语记录您的程序，以获取HIS的利益，大概是为了与公司内部和外部的人打交道。如果您帮助他完成工作，从长远来看，当您要求他提供更多硬件，人员或加薪资金时，这应该对您有利。毕竟，他要求您做更多的工作。

我认为BDD可以很好地解决这个问题，尽管您的项目似乎已经接近完成，所以现在很难实施，所以它更适合将来参考。

对于BDD，用例被描述为人类可读的文档，然后将其转换为自动化功能测试。

这个请求可能是学习ANTLR之类的好时机。采取ANTLR，采取语言的语法，解析所有代码，遍历AST并为每个节点生成基于模板的描述，i++其描述为increase i by 1 using postfix increment operator。那真的很有趣。您的老板可能还希望将此工具包含在构建脚本中，因此，每次进行任何更改时，他都会收到约20 MB的电子邮件，其中描述了新版本的功能。

PS开个玩笑，他是个白痴。

尽管我同意这是一个不合理的请求，但是您的老板可能会喜欢Docco的输出，该输出将您的代码和逐行或逐条注释分离为两列HTML输出，并且代码位于一个一边散文。当然，您必须自己输入评论，但是即使对于非技术读者来说，演示文稿也是很好的恕我直言。例如，请参见Underscore.js的带注释代码的逐行注释部分。也有Python和Shell脚本版本。

您的老板很可能没有消息灵通而受到威胁，但实际上却是一个合理的人。如果是这样，与他/她进行推理可能会起作用-随意交谈，您承诺提供“他真正想要的东西”，即；程序执行情况的散文指南。

如果是“我的路还是高速公路”，最好现在检查一下汽油。

您可以使用诸如黄瓜之类的行为驱动设计框架来编写一些验收测试。那不会解释代码；它将以自然语言解释其功能。它还具有可执行的优势，因此您始终可以确保文档是最新的，因为如果不是最新文档，则测试运行程序将为红色。

观看介绍视频。当您找到新老板时，这可能是一个很好的转移……;-)

您的经理几乎肯定会因他不了解他所管理的人员所做的事情而感到沮丧，并且他没有了解他们产生的结果的背景。

我怀疑他是否彻底解决了这个问题，乍一看对他来说似乎很明智。但这主要是因为他不了解编程代码实际上是什么。

任何程序员都理解此请求的荒谬性，但我们这样做是因为我们凭直觉知道一旦您超过了该语言，所揭示的就是算法，它同样是隐秘的。

// 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

这里的问题是，尽管注释解释了每一行的功能，但是除非您了解所有含义，否则您仍然不知道代码的实际功能。很明显，如果您是一名程序员并且之前已经看过这种模式；但向只有销售人员了解的人展示，阅读评论后，他会像以前一样感到困惑。

通过教老板一些基本编程，您实际上可以节省时间。如果他想阅读您的代码，请给他提供能够做到的工具。大多数语言在语法上都非常紧凑，学习结构只需要一两个小时。几乎可以肯定，他会在几天后放弃，但是至少他会知道自己正在传递什么，更重要的是为什么他不想阅读您的代码。

恕我直言...如果他负责完成任务，他应该知道其工作原理... :)