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

#1 楼

这里的所有其他答案和评论确实让我感到困惑，因为它们与我的第一个反应背道而驰，也与我在同事中目睹的态度背道而驰。因此，我想描述一种替代方法，仅是为了表达异议。

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

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


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

我认为对话框不应该出现在这里：


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

#2 楼

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

这就是说，定义（这里很差的）质量标准非常重要：


合同质量标准：交付的代码必须符合，或者否则就违反了合同。没有选择。
正式的企业质量标准：即使完美运行，不符合要求的代码也会被许多人认为是劣质产品，以至于您在将它们全部转换为更好的做法之前已经过时了。更糟：众所周知的工具可用于自动化和验证此类质量指标（例如，声纳立方体）。几乎没有选择。
由客户两个人定义的临时标准。在这里您可以进行讨论。希望：-)

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


生产力问题：编码进行了两次（一次用英语，一次用代码）。
准确性问题：如果代码中进行了更改，则必须在注释中进行更改，否则注释可能变得无用。
重构问题：由于重构工具无法处理注释中的变量名。
风险问题：评论的含糊不清（或过时）可能会引起混乱并增加错误的风险。
数量不是质量

这是关于StackOverflow的无用注释的有趣集合。

这篇文章认为高注释率甚至可能是代码气味的标志。

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


干净的代码（建议这本书给您的客户：其中有一个令人信服的部分，专门用于注释和自我记录代码。
文档实践：最难掌握的内容，因此也是最有价值的信息，例如类之间的关系和交互，最好在单独的文档中进行记录（例如，以UML图片而不是1000个注释字？） />
如果仍然不相信客户，则可以提出实验性的替代方法，使用工具自动生成带有注释的文档，例如javadoc或doxygen。提议将重点从数量（代码的25％）转移到质量（生成可理解的Javadoc）。

#3 楼

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



客户真的希望获得25％的评论，还是客户想要您的代码尽可能具有描述性？

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

我想您的客户有一些伪知识并且想要代码可以很好地记录下来，并且易于维护且价格便宜，并且它的工具是注释（在他的脑海中）。

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

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

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

#4 楼

这让我想起了您看到的那些愚蠢的Stack Overflow答案，其中包括一行，从字面上是“一些文本以达到最小字符限制”。

发生这种情况时，可以将参数两组人都错了：提交信息格式不正确的人，然后在系统提示他们添加更多实际物质时又添加了人工噪音

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

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

“但是我们还能怎么达到25％？”通过写实质内容的实际评论。使用更多的单词，更好的单词，最好的单词来记录功能的效果。扩展您的解释。更详细地描述一些极端情况。最终，尽管它们是客户，所以请充分利用它。但是我的意思是“最好”。到目前为止还没有发生“最糟糕”的情况。

#5 楼

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

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

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

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

PS-查看标准Java容器的代码以了解您的情况可以达到哦70％左右...

#6 楼

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

#7 楼

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


如何应对？


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

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

他们一旦问到我为什么要教他们好名字的目的是避免发表评论。

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

#8 楼

是的，我理解您对愚蠢规则的无奈。我已经阅读了很多程序，这些程序带有无用的注释，例如

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”和一个新日期。如果客户提出疑问，请告诉他们您认为有必要保留历史记录。等等等

#9 楼

任意量度似乎已成为太多项目中不可或缺的事实。

愚蠢的需求中经常出现这种情况，例如最大的循环复杂度导致代码更复杂，因为不必要地将函数拆分为确保合规性，或者由于文件超出了任意SLoC长度而被分割的文件

注释应添加到代码中，并说明正在发生的事情（而不仅仅是重复代码！）。

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

#10 楼

在短期内，您无能为力。继续进行下去。

您还应该忽略我在此线程中看到的关于被动激进抗议和代码中愚蠢笑话的所有愚蠢想法。

一旦有了与客户建立了信任关系，他们将更能倾听您的推理-您可能会发现，这曾经是一个有影响力的人提出的愚蠢要求，而且内部几乎没有支持。 >
在没有客户许可的情况下，任何情况下都不得违背。

#11 楼

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

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

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

如果您认真地编写代码并为维护团队提供上下文，该要求将自动满足。因此，不要对此发脾气！

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

#12 楼

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

对他们来说，他们所知道的一切都是众所周知的。

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

使用此标准，您可以迫使人们开始发表评论。

他们可能在99％的时间内写下无用的评论，但有时他们可能会写下“大家都知道”的一件事，而团队中的某个新人实际上可能不会花16个小时来寻找错误（已经解决了，但是由于另一个原因而被撤消了），这在代码的那个位置带有注释是很明显的。偶然的程序（尤其是在进行快速测试时，“被破坏”的部分不明显）。