我的客户希望在我当前的项目中获得25％的评论，如何做出反应？[关闭]

初级开发人员在这里。

我目前正在为我公司的大客户开发Web应用程序。我上个月开始的。客户希望在其每个软件项目中至少获得25％的评论。

我检查了以前的应用程序的代码，这是我的观察结果：

• 每个文件都以注释块开头（程序包，最后更新日期，我的公司名称和版权）

• 所有变量均以其名称注释 // nameOfCustomer public String nameOfCustomer

• 所有的getter和setter方法都被评论了

• 很少有用的评论

似乎开发人员只是提出了尽可能多的评论，以达到25％的门槛，无论质量和实用性如何。我的公司告诉我，“我们按照客户的要求去做”。

我没有直接与客户谈论此事。到目前为止，这是我的论点：

• 没用的线来读书和写字（浪费时间）
• 注释有时未更新（造成混淆的原因）
• 开发人员不太可能使用或信任真正有用的评论

您对这个问题有何建议？我应该如何处理这种情况？

此处的所有其他答案和评论确实让我感到困惑，因为它们与我的第一反应背道而驰，也与我在同事中目睹的态度背道而驰。因此，我想描述一种替代方法，仅是出于反对声音的目的。

这个答案的指导原则是“使顾客高兴”。满足客户的要求并不仅仅意味着满足他们的期望。这意味着要深刻理解他们的要求，以至于您可以按照他们的意思来解释他们所说的话，并且超出他们的要求。其他答案似乎遵循恶意合规性原则，我认为这很可恶；而且还有可疑的商业惯例，因为这是获得回头客的不好方法。

对我来说，当我听到客户说“我要25％的评论”时，这就是对话的开始。对我来说，很明显，这里的含义是“我想要大量描述性文本，以便该代码库的新手可以快速启动并运行”，而不是“我希望您在某个语法类别中添加随机性”作为其他答案。似乎正在接受。我会认真对待该请求，并打算编写许多描述性，有用的评论，指导新手了解代码的结构，指出令人惊讶的工程决策并概述其中的推理，并提供高级英语复杂代码段的描述（即使它们没有任何意外）。这种意图和理解是起点讨论的内容-那是在我们甚至开始谈论之前。对我来说，请求的含义非常清楚，以至于甚至不需要澄清。但是如果您不确定，您当然应该向他们查询！

好吧，如果那是起点，那么对话框会去哪里？对话框的下一部分是这样的：

1. 我希望这可能是一项重大的额外工作，可能在项目的第二阶段中，超出了他们关心的工具的生产范围。可能需要花费几分钟的讨论时间来讨论此过程以及为什么要进行额外的工作，但在这里我将省略它，因为作为一名专业程序员，我希望您知道做出好的评论有多么困难。
2. “认真的额外努力”意味着我们可能需要更长的时间预算和更大的货币预算；否则我们可能需要减少功能预算；要么我们可能需要在评论的质量和数量上做出让步。这部分需要进行一些协商。但是我认为，您应该非常提前做好这项额外工作的成本，并确保它对客户来说是如此重要，以至于他们愿意承担这些成本。如果它们很棒-太好了！您获得了额外的时间和金钱，并且他们获得了高质量的评论。每个人都赢。如果事实证明评论功能对他们而言并不那么重要，以至于他们愿意失去使小部件杂乱无章的功能，或者愿意将截止日期延至20x6的Granuary后期，那么每个人都会再次获胜：他们获得了他们所拥有的产品想要，您不必花费额外的精力来创建高质量的评论。

这里就是我认为对话应该不走：

3. 不要以低质量的评论威胁客户。让他们帮助您选择他们想要花费的工作水平以及他们愿意为此付出的努力。不要向他们承诺25％的评论，然后告诉他们您打算在项目建立后通过自动生成随机性来兑现这一承诺。
4. 不要隐藏你的计划。不要向他们保证25％的评论，然后自动生成随机性而不告诉他们这就是您要做的事情。当他们注意到（不是这样）时，你们俩都会浪费很多时间：他们对他们获得的产品不满意，并且您会得到负面的口碑。
5. 不要试图说服他们他们不想发表评论。他们显然希望发表评论。讨论各种方法之间的权衡：是的！讨论使代码库成为新手友好的替代方法：是的！告诉他们他们不知道想要什么：嗯，不。您想与他们合作，让他们得到他们想要的东西；因此，请了解这是什么，并弄清楚如何在他们批准的预算中最好地将其交付给他们，并在资源不足的情况下优先考虑他们最关心的功能。
6. 不要为评论很难写任何借口。编写代码很难。调试代码很难；写评论很难。如果很简单，他们就不会雇用您。只需跳过投诉，直接指出他们关心的重点，即所需的额外努力如何影响他们。

顾客为王。因此，作为承包商，您应满足客户定义为质量标准的任何要求。否则您可能会被淘汰。

话虽这么说，如何定义（这里很差）质量标准非常重要：

• 合同质量标准：交付的代码必须遵守，否则违反合同。没有选择。

• 正式的公司质量标准：即使完美运行，不符合要求的代码也会被许多人视为质量低下，以至于在将它们全部转换为更好的做法之前，您会过时了。更糟糕：可以使用众所周知的工具来自动化和验证此类质量指标（例如，声纳立方体）。几乎没有选择。

• 客户的几个人定义的临时标准。在这里您可以进行讨论。还有希望 ：-）

在后一种情况下，可能会有一定的灵活性，您可以尝试以外交方式指出这一点。这里有一些反对客户标准的论点：

• 生产力问题：编码完成了两次（一次用英语，一次用代码）。
• 准确性问题：如果在代码中进行了更改，则必须在注释中进行更改，否则注释可能变得无用。
• 重构问题：因为重构工具无法处理注释中的变量名。
• 风险问题：评论的含糊不清（或过时）可能会引起混乱和增加错误的风险。
• 数量不是质量
• 这个关于StackOverflow的无用注释的有趣集合。
• 本文认为，高注释率甚至可能是代码气味的征兆。

但是，您可以只倡导更好的方法，而不是反对坏处并与客户面对面：

• 干净的代码（向客户推荐这本书：有一个令人信服的部分专门用于注释和自我记录代码）。
• 文档实践：最难掌握的内容，因此也是最有价值的信息，例如类之间的关系和交互，最好在单独的文档中进行记录（例如，以UML图片而不是1000个注释字？）

如果仍然不相信客户，则可以提出一种实验性的替代方法，使用工具自动生成带有注释的文档，例如javadoc或doxygen。提议将重点从数量（代码的25％）转移到质量（生成可理解的Javadoc）。

客户希望在其每个软件项目中至少获得25％的评论。

客户是否真的想要25％的注释，或者您的客户希望您的代码尽可能地具有描述性？

恕我直言，客户知道他想要什么，但不知道他需要什么。由于客户本身不是开发人员，而是从自己的工作人员/客户那里获得反馈，因此您的客户只会看到冰山一角。

我猜您的客户有一些伪知识，并且希望代码能被很好地记录下来，并且易于维护且价格便宜，而用于此目的的工具就是注释（在他看来）。

尝试与他交谈，并准备一些代码片段，这些片段应具有写得很好的解释自己的代码，以及另一个写得不好的带有注释的代码。仅几行。如有需要，请显示此文字，并将其用作您的文字图片。

与您的客户/主管/任何人交谈，并尝试告诉他们版本控制的现代原理（文件开头无需注释）和干净的代码（我也推荐这本书），并因此产生自我解释的代码。

也许，如果您可以证明它足够好，并使您的客户理解他想要干净的代码，而不仅仅是注释，那么您和您的团队可以编写更好的代码（注释少得多），并立即表明您是一个值得保留的优秀开发人员。

这让我想起了您看到的那些愚蠢的Stack Overflow答案，这些答案由一行组成，紧接着是“此处的某些文本以达到最小字符限制”。

发生这种情况时，可能会引起争论，认为有两类人有错：

1. 设置限制的人—显然这是过分的，并且会阻止人们在不增加人为噪音的情况下提交正确格式的信息

2. 提交信息格式不正确的人，然后在系统提示他们添加更多实际物质时添加了人工噪音

有时，一个问题既简单又话题性大，没有什么可说的了。但是，这种情况极为罕见。在几乎所有情况下，还有很多要说的内容。如果没有别的，那么应该很明显地知道绕过字符限制的方法不仅仅是将随机噪音转储到您的帖子中。

您面临的此评论情况几乎相同。您的开发人员已提出评论请求，并通过将随机噪声转储到其代码中来实现该请求。在变量声明旁边记录变量名称是故意破坏行为。那应该永远不会发生。

“但是我们还能怎么达到25％呢？” 通过写实质性评论。使用更多的单词，更好的单词，最好的单词来记录功能的效果。扩展您的解释。详细描述边缘情况。

但是，回到原始点，客户端在这里也有部分过错，因为“源代码的25％”是极端任意的。最终，尽管它们是客户，所以请充分利用它。但是我的意思是“最好”。到目前为止，还没有发生“最糟糕”的情况。

我不知道此要求有什么大惊小怪的。

仅通过代码的基本脱氧，您就可能已经达到10％左右。接下来，让我们再考虑一下您为自己写的评论的5％（有些人写得更多，但是如果您没有誓言的话，这5％似乎是保守的估计）。此时大约是15％（是的，我知道，90％中的5％小于5％，请不要挑剔）。如果您的氧含量低于10％，则可能是您的方法很长；通常最好将它们分成较小的（主要是私有/受保护的），或使用更多的通用帮助器类等。

现在，对于其余的注释文本-将设计注意事项和使用方案放在类/文件级注释中。有一些表或ASCII艺术（或doxygen代码，在渲染时会生成外观更好的东西）。我当然不知道您的项目是关于什么的，但是我相信您可以做到这一点而无需任何虚假的评论（除加氧样板之外），并且接近25％。

如果仅是20％，而不是25％-我敢肯定，客户只是随便说了这个数字，就可以了。无论如何，与他们交谈以讨论评论应包含的内容；并向他们显示示例注释文件，看看他们是否满意。如果是的话，就是这样，如果他们认为缺少了什么，他们会告诉您缺少了什么。他们不会告诉您“我们无法建议任何可能的额外评论，但我们仍然希望您添加一些评论”。

PS-查看标准Java容器的代码，看看如何达到70％左右。

在您的代码中包含25％的注释是一个绝佳的目标，它会使客户满意。现在应该写25％的糟糕的填充器注释，例如“ i + = 1; //将i增加1”，这样就可以花点时间，写出有用的注释，并享受做事应该得到的报酬无论如何。

我们都知道这是胡扯。有趣的问题是

怎么反应？

我坚信让问题可见。在这里，我会利用金钱在谈论的事实。

请我这样做，可以肯定的说，这会使我的出价提高1％。哦，但是它将在以后的任何维护出价中增加20％。

只有他们问我为什么要教他们，好名字的目的是避免评论。

作为替代方案，我将建议创建文档，以期使维护程序员具有一组定义的假定资格，以加快项目背后的想法。或可以肯定，我可以给您25％的评论。由你决定。

是的，我理解您对愚蠢规则的无奈。我读过很多程序，这些程序无用的注释，例如

x = x + 1; // add 1 to x

我对自己说，那就是加号的意思！！哇，谢谢你告诉我，我不知道。

但这就是说，客户正在支付账单。因此，您给他们他们想要的。如果我在一家汽车经销店工作，并且一位顾客说他想要一辆皮卡车，那么我不会与他争论他是否真的需要一辆皮卡车，并向他询问他期望在皮卡车里买什么。我要给他卖一辆皮卡车。

好的，有时候客户所说的和他真正的需求相距甚远，以至于我试图与他讨论此事，也许说服他同意更理性的事情。有时候这行得通，有时却行不通。最后，如果我不能改变他的想法，我就给他他想要的。如果他稍后回来说：“哦，那真的不满足我的业务要求，那么我们可以向他收取更多的费用，以执行我们第一次告诉他的事情。您可以与客户进行多少谈判取决于他们对您的专业知识的信任程度，与您的合同与组织的契合度以及坦率地说他们的胆识。

在极少数情况下，如果我认为要求由我自己决定，那么我会失去合同，因为我认为要求不正确。

请记住，与您公司进行谈判的人员可能是也可能不是发明此25％规则的人。从高处强加于他们可能是一条规则。

我看到五个可能的响应：

一。说服您的老板或与客户进行谈判的所有人。奇怪的是，这将无济于事，但您可以尝试。

二。拒绝这样做。这可能会导致您被解雇，或者如果公司同意您的要求，则会导致您失去合同。这似乎没有效果。

三。编写无用的注释来填充空间，这些注释只是重复代码中的内容，并且任何能够修改代码的程序员都可以在2秒钟内看到它们。我已经看到很多这样的评论。几年前，我在一家公司工作，要求我们在列出参数的每个函数之前放置注释块，例如：

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

反对这样的评论是维护负担，因为您必须使它们保持最新，这是无效的。不需要更新它们，因为没有认真的程序员会关注它们。如果对此有任何疑问，请确保向团队中的所有成员明确，无用的多余评论应被忽略。如果您想知道函数的参数是什么或代码行是什么，请阅读代码，不要看那些无用的注释。

四。如果要添加多余的无用注释，也许值得花时间编写程序来生成它们。预先进行某种投资，但可以省去很多打字工作。

当我刚开始从事这项业务时，我所工作的一家公司使用了一个程序，该程序的广告语为“为您编写文档！每个程序的完整文档！” 系统要求我们给所有变量基本上没有意义的名称，然后有一个表为每个变量赋予一个有意义的名称，因此，基本上，“自动文档”所做的就是用一个有意义的名称替换了迫使我们使用的毫无意义的名称。例如，这与COBOL一起使用时，您的程序中会有一行显示

MOVE IA010 TO WS124

他们会生成一行“文档”

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

无论如何，肯定可以编写一个程序以相当容易地生成同样毫无价值的文档。像这样读一行

a=b+c

并产生评论

// add b to c and save result in a

等等。

五。充分利用愚蠢的规则。尝试写出有用和有意义的评论。嘿，这可能是个好运动。

哦，顺便说一句，我可以补充一点，就是您始终可以衡量指标。

我记得曾经有一位雇主说过，他们将开始根据我们每周生产多少行代码来衡量程序员的生产力。当我们在一次会议上被告知时，我说，太好了！我可以轻松提高自己的分数。没有更多的写作

x=x+4;

相反，我会写：

x=x+1;
x=x+1;
x=x+1;
x=x+1;

循环？算了，我将代码复制并粘贴十次。等等。

因此，在这里，如果他们要计算注释行，请使每行简短，并在下一行继续进行。如果注释中的内容发生变化，请不要更新现有注释。在上面加上一个日期，然后复制整个文本并输入“ Updated”和一个新日期。如果客户提出疑问，请告诉他们您认为有必要保留历史记录。等等

在许多项目中，任意指标似乎都是生活中不可或缺的事实。

通常在愚蠢的要求中会看到这种情况，例如最大的循环复杂度导致代码更复杂，因为不必要地拆分函数以确保一致性，或者由于文件超出任意SLoC长度而拆分文件

注释应添加到代码中，并说明发生了什么（而不仅仅是重复代码！）。

就是说，如果这是您的客户想要的，并且您的公司已同意提供，则除非您的质量检查经理提出了常识，否则您将陷入困境。

在短期内，您无能为力。沿着这个走。

您还应该忽略我在此主题中看到的关于代码中被动的积极抗议和愚蠢笑话的所有愚蠢想法。

与客户建立信任关系后，他们将可以更好地倾听您的推理-您可能会发现，这曾经是一个有影响力的人提出的愚蠢要求，而且内部几乎没有支持。

在没有客户许可的情况下，您绝对不能违背它。

我对我的同伴程序员缺乏想象力感到失望。

在我看来，客户做了一些研究。他可能在某个地方读到，质量代码通常包含大约25％的注释。显然，他关心/担心将来的维护工作。现在，他如何在与合同相关的需求文档中具体说明？那不容易。这甚至是不可能的。但是他想确保自己会从自己的金钱中获得价值，因此他列举了一些质量指标。

这对我来说根本不是愚蠢或荒谬的。编写需求的人很可能不是程序员。他们可能在较早的项目中经历过糟糕的经历。他们的维护人员抱怨：“没有记录下这种狗屎！”。当他们为下一个项目编写新要求时，它就在耳边响起。

如果您认真考虑编写代码并为维护组提供上下文，那么此要求将自动满足。因此，不要因此而成为猫！

最后，无论是21％还是29％，没人会在意。客户将由一些独立的开发人员审核您的内容，他最好了解您的操作。

我遇到了许多程序员，他们不了解目前尚无法在该项目上工作的人。

对于他们来说，他们所知道的一切，每个人都知道。

如果某人不了解他们目前所知道的一切，那么这些人就是他们的“白痴”。

有了这个标准，您就可以迫使人们陷入撰写评论的习惯。

他们可能会在99％的时间内写出无用的评论，但有时他们可能会写下“大家都知道”的一件事，而团队中的某个新人实际上可能不会花16个小时来寻找错误（某人已经解决了，但后来由于另一个原因而被撤消），这在代码的那一点带有注释是显而易见的。

在带有明显错误的行中添加注释还可以帮助避免将来的程序员意外完全破坏程序（尤其是在进行快速测试时，“被破坏”部分不明显）。