我被特别要求我逐行（或酌情-例如逐个图像等）给出我的老板希望能够阅读和遵循的解释或评论。
由于他不是程序员，所以他无法遵循代码，因此希望将其全部翻译成英语。
以前有人被要求这样做吗？
我已对所有源代码进行了注释，并使用JSDoc生成了所有函数，变量等的完整文档，并包括一个实现示例和完整的演示工作，并在整个注释中进行了演示。
还有其他方法可以注释非程序员的代码吗？
这不是合理的要求，对吗？
UPDATE
最后，我设法解释了为什么没有充分利用时间来完成他的要求。他是一个理性的人，只是对我的工作不了解。一旦他看到了这篇文章，我想他很快就会明白这不是正常的要求。有关技术问题的说明），以及该程序主要逻辑的非常宽泛的流程图，供老板遵循。 />
#1 楼
不，这不是一个合理的要求！那是一个非理性的想法，尽管可行的代价如此之高，但它绝不应该实际完成。对功能和子例程的概述是合理的，但并非“解释”每条代码行都是合理的。对他来说，学习手工语言比阅读语言更有效。他接下来要问的是将数学公式转换成英文文本。尽管肯定有可能带来很多错误和误解的余地，但绝不应该这样做。就像将代码“翻译”成英文一样。
评论
有趣：请去阅读Richard Feynmans的物理讲座。您会发现它很多都是用英语精心措辞的论点（如果X则Y必须为真，因此Z ...等）。一点数学。我要说的是，您可以用英语解释事情。您是否应该是另一回事。
–quickly_now
2011年9月7日上午10:14
@quickly_now-很久以前在大学期间阅读了它们。不错的阅读。我同意，您可以解释它-当您要向其解释的人员已经理解其背后的“抽象”（代码，数学方程式及其含义...）时，可以使用任何语言进行解释// t-您将无法使用任何语言进行解释。
–浏览
2011年9月7日在18:59
@Rook-好点。向原始部落解释量子力学，其词汇仅限于麋鹿向哪个方向移动。
–quickly_now
2011年9月7日23:16
我有时会得到您的经理的“意图”，以进行微观管理。但是，如果代码本身非常清晰，那么他可以将其阅读为英文文本。
– Arvind Chinniah
2011年9月13日10:00
#2 楼
你有设计文件吗？这些是该代码的英文解释。非编程经理应该不需要更多。评论
这就是为什么我指定“非编程经理应该不需要的更多”。
–激进主义者
2011年9月6日于20:16
@Loren Pechtel：我想在此放置站点，并观看此人实际阅读的页面“创建一个名为X的整数变量。将其设置为0。创建一个名为Y的整数变量。将其设置为0。创建一个名为Z的整数变量。将其设置为0.创建一个名为X位置的整数变量。将其设置为0.创建一个名为Y位置的整数变量。将其设置为0.创建一个名为Z位置的整数变量。将其设置为0.创建一个名为的整数变量X旋转。将其设置为0。创建一个名为Y旋转的整数变量。将其设置为0。创建一个名为Z旋转的整数变量。将其设置为0。“ ...
– FrustratedWithFormsDesigner
2011年9月6日在21:24
@Frustated使用语法高亮显示要容易得多！ “ [p32767，l21，c8]将pX增加一个整数的大小。将Sum增加px指向的值。将i增加1。如果i小于3，请转到第32768页的第17行，第42列。否则，请转到32767页第21行第8列。”
–玛蒂·乌尔哈克（Mateen Ulhaq）
2011年9月6日23:33
@muntoo，您需要内联所有这些功能，因此不必在页面之间来回跳转。否则，在恢复堆栈时可能会遇到很多麻烦。
– Kibbee
2011年9月7日于1:08
@沮丧：那么你在想谁的声音？我无法在Sean Connery和Morgan Freeman之间做出选择。
– Beta
2011年9月7日，下午1:57
#3 楼
是否有年度最佳微型经理奖？听起来你的老板值得提名。认为自己需要逐行理解代码但又不想学习如何直接阅读代码的人，可以像想象中的那样完美。成为开发人员的一个优势是，理解代码的困难至少在详细的实现级别（至少是通过非技术管理）会在一定程度上阻止微管理，因为即使是最艰苦的工作，核心微经理认识到他们在那个级别上是头疼的。但是老板的天才也许找到了打破硅幕的方法。
而且，作为奖励，即使在他使用英语翻译开始提出各种改进建议之前，我也浪费了大量开发人员的时间（我假设他比Windows更好地编码。程序员，即使他看不懂代码，也可以在有人翻译后立即分享他的智慧，否则他为什么需要翻译每一行？）。
所以，不，这不是一个合理的要求，我以前从未听说过。我为你感到。我认为每个人都可能需要静静地寻找另一份工作，因为一旦他开始使用代码转换作为管理工具，这可能将成为一个残酷的工作场所（或更糟糕的工作场所）。
从好的方面来说，也许您可以根据自己的情况命名一个新的反模式？在蒙蒂Python短剧之后，吸烟者试图通过使用带有可笑的错误翻译的匈牙利短语集来与不讲英语的人交流，“反匈牙利短语集”反模式如何？
评论
+1用于诊断微管理。用我自己的话说：把f___拿走！
– tdammers
2011年9月6日18:35
@tdammers：幸运的是，我可以对老板说这种话。除了当老板，他还是个好家伙！
– heltonbiker
2011年9月7日，下午1:28
需要了解代码的每一行的经理称为程序员。
–詹姆斯P.
2011年9月7日14:46
#4 楼
与他坐下，通过10行代码与他交谈。解释每个细节，直到你们俩都同意他理解他想要的程度为止。从您的角度来看。在我的书中那是一件好事。想象一下，如果我不得不在无法提出问题的情况下解释所有这些问题，那么我怎么可能知道要包括的内容以及要忽略的内容？结果将花费多少时间对您有用？现在您要我用这种方式做几行？评论
在花了两个小时解释了十行之后，请确保他理解还有50,000（或其他）行代码需要解释。
–HLGEM
2011年9月6日17:43
实际上是一种非常明智的跟进方式。让他看到自己的方式的无知。
– Kibbee
2011年9月7日，1：13
@reinierpost：您的方法是天才。
– heltonbiker
2011年9月7日，下午1:31
如果要执行此操作，请首先告诉老板，这通常是个坏主意，然后进行演示。如果您不这样做，则可能看起来像是在给他拉上一个“把戏”，使他处于防守状态。
–nerdytenor
2011年9月7日下午16:31
永远不要告诉别人他们的想法不好！但是，您可以讨论如何使它们实现，甚至可以给出一些捷径的想法。如果这使他们得出结论：这个想法不可行，或者使最初的想法变成完全不同的东西，而他们应该在某个时候注意到这一点，他们就会耸耸肩说：这就是生命。
– reinierpost
2011年9月8日下午12:28
#5 楼
我认为这不是一个合理的要求。源代码不是要用英语（或与此有关的任何其他语言）阅读。如果是这样，我认为您无法对此做任何事情。您将不得不编写文档，或者说服他/她雇用某人来审核您的代码。评论
即使使用英语翻译，非程序员也可能会相信：/ *并且此行会将存款转移到正确的帐户* / deposits.TransferAll（acctInfo）;
– IAbstract
2011年9月6日15:45
如果老板“害怕您要使您的代码执行他不赞成或不知道的事情”，这将无助于减轻他的恐惧。由同一人提供编写代码的翻译。是什么阻止他们说谎呢？这里还有其他事情。
–mmc
2011年9月6日在21:47
COBOL应该以英语阅读。
–oosterwal
2011年9月6日在22:51
也许他正在尝试弄清楚代码是做什么的，以查看他是否同意推理并获得更好的想法。无论如何，这样做不是他的工作，至少不是那样。
– heltonbiker
2011年9月7日，下午1:26
#6 楼
真的很简单：由于您的程序员技能而被录用
您的经理没有这些技能
Ergo，您的经理不应该有理由期望能够完全了解您的工作
我在上一份工作中也有类似的经历。我的经理是一名会计师（因此非常注重底层细节），并且不理解或不真正信任编程。她无法理解，作为一个非技术人员，她不应该期望能够掌握我所写内容的细节。在多次索要过多文档并要求培训非技术用户如何管理和更改代码的请求之后（是的，真的），我停止试图欺骗她，并彻底拒绝了。我以前解释的类比很简单：
我不是会计师
我不应该期望了解我们帐户中的每笔交易或过帐
并不表示这些帐户是错误的或不可信的，仅仅是因为我不理解它们
通过信任编写它们的人就可以做到这一点
最后，这在我看来，这就是：一个难以信任员工的经理；或担心他们会离开，并认为这是缓解这种情况的有效方法。
唯一的解决方案是坐下并解释为什么这没有道理。您的工作是理解代码，并使具有与您类似的技能的人（而不是您的经理）理解它成为可能。向他们显示此线程可能是一个好主意（或一个非常非常糟糕的线程，取决于他们的个性）。
评论
您的经理如何接受您的解释？
–杰夫·马丁（Jeff Martin）
2011年9月7日19:56
完全和您预期的一样。 ;）但是，已经提出了要点，并且请求也停止了。我不知道那是因为我已经说服了她我的论点是正确的，还是她认为这不值得麻烦而放弃了。
–约翰N
2011年9月8日在7:21
#7 楼
逐行，很荒谬。我可能建议提供从注释生成文档并将其提供给他的方法。这足以应付我过去从事的许多加拿大政府拨款和审计工作。他不会逐行获得，但他会得到逐个方法，这种方法应该比他需要的粒度还要细。
一些现有的解决方案，取决于您的平台：
C＃：沙堡
Java：javadoc
“ C ++，C，Java，Objective-C， Python，IDL（Corba和Microsoft风格），Fortran，VHDL，PHP，C＃，并在某种程度上是D。” ：doxygen
评论
由于有Pas2Dox，请将Delphi添加到doxygen列表中；-)
–Fabricio Araujo
2011年9月6日在20:39
转到沙堡链接。看起来印象深刻。单击“文档”选项卡。请参阅消息“该项目还没有文档。”看起来比印象深刻的少。
–卡兹龙
2011年9月7日15:41
#8 楼
对于他而言，学习阅读代码要比将任何有趣的应用程序的整个代码翻译成英语要快得多。此外，我们使用COBOL进行了尝试，但这完全没有帮助。如果他不愿意学习，而只想让他的愚昧无知别人的问题，那么您就是一个认真负责的上司。评论
我认为英语应该是语言。老板应该要求所有软件都以DSL（特定领域语言）编写，然后他才能更改系统的工作方式。
– David d C e Freitas
2011年9月7日下午13:34
我认为提到Cobol可以总结一下。任何打印出一个简单的“ hello world”的人都知道这种语言的可笑性。这是朝着易于理解的方向迈出的很好的一步，但过于正式。
–詹姆斯P.
2011年9月7日19:45在
#9 楼
请利用您的技术专长来追求您的老板。让他知道，这样做和第一次编写代码所花费的时间一样长（请随意延长它的时间。）
问他这份文件的最新信息。通知他所有编码更改现在至少需要两倍的时间。提醒他有关＃1和＃2的问题。
像所有不好的解决方案建议一样，最好找出问题所在。也许您的老板因高层管理人员遇到了技术问题，并且因为无法回答而感到尴尬。他可能最关心的是代码的特定部分，因此您可以将这一繁重的工作限制在该区域。
通过提交示例，他可能会得出以下结论：如果您不了解编码的工作原理（什么是循环以及对所有这些项目的作用是什么？）就没关系它使用的是哪种语言。他最好从高级用户的角度理解应用程序。我认为让您知道他愿意写真实的代码/提示对您来说很公平-我正在寻找另一份工作。
评论
我们需要谨慎地将任何人都描述为“白痴”。虽然使我们作为程序员个人满意，但我认为这不是专业的，任何经理的任何要求，无论多么奇怪，都应根据其优点来对待。
–funkymushroom
2011年9月6日18:53
@funkymushroom：这个请求的优点是他是个白痴。
– DeadMG
2011年9月6日在21:04
@funkymushroom-我认为我们可以在此站点上略微提及。毕竟，您去了时髦蘑菇。
– JeffO
2011年9月6日在22:25
@Jeff：点好。我绝不是固执己见的人。但是，有两种“白痴”。我曾与“恶意白痴”和“无知白痴”一起工作过。第一个应该被忽略，他对我们的职业有害，第二个可以是一个好盟友，因此我们应该教他。
–funkymushroom
2011年9月7日14:09
@funkymushroom-同意，所以我把它拿出来了。
– JeffO
2011年9月7日在17:33
#10 楼
为什么？逐行注释不合理，但是我要问的是：您为什么要这个？
是因为...
您想全面了解该软件的功能（不一定是怎么做）？
要确保其他程序员可以在我离开时接手该项目？
您想看到我在做真实的工作吗？
这个请求背后可能有合理的愿望，您也许可以通过弄清并满足需求来使老板满意。 br />
更新
基于
Mikey's的评论，也许我说得有些直率。我并不是说您应该从字面上说“为什么要这么做？”，而是您应该找到答案。措辞和语气有很大的不同。具体来说，您可以这样说：“我一直在考虑您的要求，以解释每行代码的每一行。
我想知道也许我在工作中没有很好地与您沟通
。您真正想了解我们的代码是什么，或者关于我在做什么？您想在这里完成什么？”但是更有可能他不知道这个要求有多怪异，并且脑子里有一些合理的目标。
如果没有，那就开始完善简历。 :)
评论
-1为该答案：如果您想坚持自己的工作（或至少自愿辞职），您不应该问这样的老板“为什么”？正如其他人所建议的，这是必须加以完善的东西。
–矢量
2011年9月7日，下午3:14
我不同意Mikey的评论。盲目遵守命令是愚蠢的。问“为什么？”根据每个请求，我节省了无数小时的不必要工作，并在此过程中为公司节省了很多钱。这就是所谓的协商，那些不惧怕老板的人会慷慨地这样做，并且会产生很大的效果。当为我工作的人提出一些建议时，我也会问他们“为什么？”也一样在这两种情况下，它都在寻求辩解，这样做是完全可以接受的。
–苏联
2011-09-8 9:34
#11 楼
听起来是尝试识字编程的好机会。去谷歌上查询。 :)但是...不一定是完全不合理的要求。您的工作（更重要的部分是imo）是您与其他开发人员以及（如有必要）非技术人员进行算法交流的一部分。我认为，无法沟通的孤立无常的天才程序员总是有问题。记录”，是指变量和函数具有一种含义或责任，它们的名称清楚地反映了这一点）。您的老板可能有充分的理由要求他。也许（我只是在这里猜测）您或您的前任以坚不可摧，脆弱的代码而闻名，这就是老板的补救措施。这有点极端，但可能对您有用。我以为他知道写更好的文档需要时间（如果他不写，就应该教育他-就像写学期论文：写比阅读要花更长的时间）。
评论
我看过维基百科页面。它使我想起了学习期间看到的“结构化的<在此处插入人类语言>”。您使用人类语言用表达式逐行表示编程结构，例如if blah然后将1加到x上作为nassi-schneiderman或流程图的替代方法。这是识字编程的意思吗？
–詹姆斯P.
2011年9月7日19:51
您是此页面上唯一提到Knuth的识字编程的人-让我想知道过去40年里其余的海报生活在什么岩石下...
–cji
2011-10-24 21:43
@James：购买Knuth的“ Tex-该程序”的副本并阅读。这是识字编程。
–cji
2011年10月24日21:50
#12 楼
即使逐行翻译也无法有效传达每行代码的含义。程序员对一行代码的理解始终是在许多因素的背景下进行的。进入多段代码之类的东西，英语翻译不会比原始代码有意义。考虑一下分散在多个功能/文件之间的功能。如果不解释大量其他代码，则某些代码绝对没有意义。尝试逐行解释依赖注入中涉及的不同部分，您将明白我的意思。几乎所有超出上帝功能的程序代码的内容都需要大量的编程知识才能理解英语翻译。另外，看一下简单的if / else决策语句。没有一行一行的内容，因为下一行取决于运行时数据。下一行可能是几种可能性之一。到您解释应用程序的功能时，您将把PM变成一名程序员，并且都已经5岁了。#13 楼
由于我曾经教过编程，所以我很乐意尝试一下。他会很快发现自己得到的好处超过了他的讨价还价，
这会让我很难过，因为我喜欢解释：-)
评论
我认为这是最好的答案。我不理解尝试尝试的全部不情愿，我的意思是您将获得报酬来坐在那里并解释您的代码！糟糕，除非您的代码完全废话，否则您可能会喜欢它，而无论代码多么好，您都可能会发现一些错误和需要改进的地方。
– Bill K
2011年9月7日15:13
我有一位老师在输入通过投影仪显示的代码时解释了内容。也许这可以像驾车课一样完成。如果您至少无法阅读所有代码，则可以更好地了解正在执行的操作和操作方式。
–詹姆斯P.
2011年9月7日19:54
我正在尝试自己从事教学业务，并且给出了类似的答案。我与@Bill在一起，我对人们采取这种隐性立场感到非常失望。我们是否因为认为值得花时间解释甚至只是一小部分代码而搞砸了？
–宫阪丽
2011年9月8日在12:44
@Rei：好的或坏的态度往往会接管大批其他本来相似的人。我拥有丰富的经验（工程师，研究生，教授，顾问，长期雇员），所以我想提供一个视角。而且，多年来我的态度发生了变化。
–迈克·邓拉维（Mike Dunlavey）
2011年9月8日在16:37
#14 楼
当您提到“老板”时，这是“负责您/您的团队的中层经理”吗？还是公司的所有者？如果您的老板是负责任的中层经理，请对老板说，您是按时薪还是按薪水支付？指出要满足老板的要求公司的生产力将减少到原来的1/3。
如果您的老板是“签支票的人”，那就用外交手段向他解释同样的事情。您的工作已经从“编写代码”变为“编写代码，编写代码说明，解释说明”。
评论
为什么不这样做并拿走钱呢？您是否确定自己的唯一价值就像生成猴子一样的代码？
– Bill K
2011年9月7日15:15
#15 楼
流程图可能会给他带来更多好处。当然，这是一个不寻常的请求，对于他作为经理的说法并没有多说。评论
实际上，它告诉了我很多关于这个人的信息。
– Marjan Venema
2011年9月6日17:17
在这种情况下，这就是“不多说”的意思-确实说了很多，但是它并不能说明这个人的好事。
–约瑟夫·魏斯曼
2011年9月6日18:10
#16 楼
您的老板愿意花一些时间来理解您编写的代码，您可以从中受益。尝试向他介绍Cucumber：
http://cukes.info/
，让您的老板将来为您编写BDD测试。
评论
一段时间以来，我一直在努力让黄瓜在我的商店中使用...不幸的是，（或者幸运的是！）我的老板不在乎幕后发生的事情，只要它起作用即可。让他首先了解编写测试的好处是一场艰巨的战斗。
–Jason Lewis
2011年9月8日15:13
#17 楼
他不应该不知道这些。告诉他，在软件开发中实现可能会发生变化。活动设计如有变更，恕不另行通知。告诉他有关信息隐藏，封装和抽象的信息。从广义上讲，作为团队的一员，作为代码的客户，他应该只对代码的用途进行清晰，高级的抽象。您的代码的任何层与其他人的代码的另一层使用相同的方式。仅此而已的知识，只会减慢他的速度，并冒着他根据代码的内部运作作假设的风险。如果他必须基于这些代码构建任何类型的系统或流程，那么当您不得不更改代码时，这些假设就将不再成立。您不仅需要在两个不同的地方进行后续更改，而且还会对您的工作士气产生负面影响，从而进一步降低您的工作量。
#18 楼
英语的美丽在于混淆得很漂亮。如果您利用它来发挥自己的优势，那么您可能再也不会处理这种请求了。我将一小段代码作为示例，但其中的一个非常抽象，一点也不容易理解。然后，我将用技术英语来编写注释，就好像您是为编程书籍中的一章编写注释一样。遵循时间越长，越复杂越好。告诉他您花了多少时间来记录此功能。然后解释一下，它只是实际代码库的1％的1/10（如果可能，请使用基于代码行的实际数字，它们可能比这还差）。当他意识到自己不知道英语翻译怎么说时，并且需要20,000个工时才能完成此级别的文档编制时，他将很快退后一步。但是要非常认真地尝试完成他的任务。不要；如果您无法做到这一点，请尝试，并且他怀疑您在玩他。#19 楼
这看起来像是假日假期特别尖头上司迪尔伯特脱衣舞的候选人！乍一看，他的要求当然听起来不合理。 ，然后让他决定是否要花那么多钱。就您自己而言，算一下要满足他看似奇怪的要求所花费的时间，然后确定您是否会花那部分时间来寻找新工作会不会更好呢？为愿意将您视为专业人士的雇主工作！
评论
成本效益分析应能胜任。也许经理可以带来一些额外的好处。如果没有回报，则很难对上级管理层进行强制和捍卫。
–mbx
2011年9月7日上午9:26
#20 楼
将他带到您的办公室，并带他参观您的代码。他会从某种程度上意识到他提出了荒唐的要求，他会走开，再也不会打扰您了。
如果您不屈从于帮助他尝试理解您的代码的要求，他会发现不同但同样荒谬的方式来嘲笑您。
安抚胜过磨损的地方。
评论
+1-我一直在想-接受他的要求-不久后他可能会感到无聊和/或害怕死亡...
–矢量
2011年9月7日在3:17
+1我喜欢-“比磨损更有效”。
–迈克·邓拉维（Mike Dunlavey）
2011年9月8日下午16:41
#21 楼
如果我们有翻译“ X到英语的语言”来做到这一点，那就太好了。然后一个人可以咧嘴一笑，说，没问题，老板，一分钟之内就可以解决。然后是一封邮件，其中包含几兆字节的文本，内容为：让它成为一个包含20个元素的新整数数组。
让x成为一个存储整数的变量。 br />将x设置为0
而x小于20时，请执行接下来的2行中的规定
将索引为x的a的数组元素设置为使用参数x调用nThPrime的结果+1
将x增加1
.....
另一种选择是建议以后在莎士比亚编程。
评论
我将提出相同的建议。老板不希望有概念上的概述，而是希望逐行介绍，因此应该一天之内就可以提出一些建议，从而创建完全无用但表面上正确的文档。它是否是perl中if-eles的老鼠巢，很容易被极端情况混淆，这无关紧要，它只会识别变量声明，对变量的修改，方法调用等（请记住，它是逐行的，没有方式使代码混乱）。
– PhilDin
2011-09-8 9:33
是的，这位老板只是愚昧无知。他不知道“抽象”是什么，他也不知道英语对表达计算机程序不是很好，他无法想象他真的不想知道所有这些细节，这就是为什么他付钱给程序员。因此，他应该得到这样的教训。
– Ingo
2011年9月8日在9:44
#22 楼
我的老板想要逐行叙述我们的代码的英文解释
坚韧。
程序员，他不能遵循代码，因此希望将其全部翻译成英文。
如果他不是程序员，则不应阅读代码。完全没有。
提供高级文档。
这不是一个合理的要求，对吗？
编号
#23 楼
作为程序员，您确实有“两个”工作。第一个是创建好的程序。第二种是“卖”给公司内外的客户。
老板的要求“伤害”了您的第一份工作。记录程序需要更多时间。另一方面，他实际上是在使您在“第二份”工作上更加努力。在公司内部和外部进行处理。如果您帮助他完成工作，从长远来看，当您要求他提供更多硬件，人员或加薪资金时，这应该对您有利。毕竟，他要求您做更多的工作。
评论
逐行记录！=出售项目。应该已经有一个提供此信息的文档，称为需求。我同意您的2个职位描述，但是记录到该级别对于销售项目/系统/应用程序将无益。有适当水平的文档来介绍您的工作，事实并非如此。
– cdkMoose
2011年9月6日于17:58
我敢打赌，在这家公司写支票的人不会为这位经理浪费这么多公司资源感到高兴。
– JeffO
2011年9月6日在22:28
@Jeff O：可以。也可能是整个公司都是这样，一直到顶峰。
–汤姆·欧（Tom Au）
2011年9月6日在22:46
#24 楼
我认为BDD可以很好地解决这个问题，尽管您的项目似乎已接近完成，所以现在很难实施，因此更像是供将来参考。使用BDD可以案例被描述为人类可读的文档，然后被翻译成自动化的功能测试。
评论
到目前为止，这可能是最具建设性的建议。行为驱动的开发旨在完全满足此需求：帮助程序员及其经理/客户就软件的功能达成共识。编写描述有助于计划代码，并且运行测试证明它们仍然是准确的描述。
–内森·朗（Nathan Long）
2011年9月6日于20:53
#25 楼
这个请求可能是学习ANTLR之类的好时机。采用ANTLR，采用您语言的语法，解析所有代码，遍历AST为每个节点生成基于模板的描述，因此i++被描述为increase i by 1 using postfix increment operator。那真的很有趣。您的老板可能还希望将此工具包含在构建脚本中，因此每次进行任何更改时，他都会收到约20 MB的电子邮件，其中描述了新版本的功能。开个玩笑，他是个白痴。
#26 楼
尽管我同意这是不合理的要求，但您的老板可能会喜欢Docco的输出，该输出将您的代码和逐行或逐句注释分离为两列HTML输出，并且代码位于一边散文。当然，您必须自己输入评论，但是即使对于非技术读者来说，演示文稿也是非常不错的恕我直言。例如，请参阅Underscore.js的带注释代码的逐行注释部分。也有Python和Shell脚本版本。评论
这是我对该问题最有用的答案之一。我确实尝试使用docco，但发现它与我现有的一些注释有关，并且呈现不正确。因此，我改为使用JSDoc，并遵循google的准则来生成文档。不那么漂亮，但是非常完整，也是一种标准格式。对我而言，docco的问题是您需要构建代码以适合注释，否则这没有任何意义。谢谢你的建议。
–比利·穆恩（Billy Moon）
2011年9月7日于7:40
#27 楼
您的老板很可能没有消息灵通而受到威胁，但实际上却是一个合理的人。如果是这样，与他/她进行推理可能会起作用-随意交谈，您承诺提供“他真正想要的东西”，即；程序工作的散文指南。如果是“我的路还是高速公路”，最好现在检查一下汽油。
#28 楼
您可以使用诸如黄瓜之类的行为驱动设计框架来编写一些验收测试吗？那不会解释代码；它将以自然语言解释其功能。它还具有可执行性的优点，因此您始终可以确保文档是最新的，因为如果不是最新文档，则测试运行程序将变为红色。请查看简介视频。当您找到新老板时，这可能是一个很好的转移... ;-)
#29 楼
几乎可以肯定，您的经理会因为他不了解他所管理的人员所做的事情而感到沮丧，并且他没有了解他们产生的结果的背景。我怀疑他是否彻底考虑了这种解决方案，乍一看对他来说似乎很明智。但这主要是因为他不了解真正的编程代码。
任何程序员都理解此请求的荒谬性，但我们这样做是因为我们凭直觉知道一旦您超过了该语言，所有内容便会被揭示出来。是算法，它同样是隐秘的。除非您了解所有含义。很明显，如果您是一名程序员并且之前已经看过这种模式；但是将其显示给只了解销售的人，在阅读评论后，他会像以前一样感到困惑。如果他想阅读您的代码，请给他提供能够做到的工具。大多数语言都是非常紧凑的语法，学习结构只需要一两个小时。几乎可以肯定，他会在几天后放弃，但是至少他会知道自己正在传递什么，更重要的是为什么他不想阅读您的代码。
#30 楼
恕我直言...如果他负责完成任务，他应该知道其工作原理... :)评论
您是指经理还是程序员？
–内森·朗（Nathan Long）
2011年9月6日于20:48
有多少公司可以负担得起每个非技术经理用尽这么多开发人员的时间？
– JeffO
2011年9月6日在22:27
评论
由于历史原因而被锁定，有关更多详细信息，请参阅“锁定最受投票表决的问题”。