Questions tagged «documentation»

许多人声称“评论应解释“为什么”，而不是“如何””。其他人则说“代码应该是自我记录的”，注释应该很少。罗伯特·C·马丁（Robert C. Martin）声称（用我自己的话改写）经常“评论是写得不好的代码的道歉”。 我的问题如下： 解释复杂的算法或带有描述性注释的冗长而复杂的代码段有什么问题？ 这样，无需其他开发人员（包括您自己）逐行阅读整个算法来弄清楚算法的作用，他们只需阅读您用普通英语编写的友好描述性注释即可。 英语是“设计”成易于人类理解的。但是，Java，Ruby或Perl旨在平衡人类可读性和计算机可读性，从而损害了文本的人类可读性。人可以更快地理解英语，而他/她可以理解具有相同含义的代码（只要操作不琐碎）。 因此，在编写了用部分人类可读的编程语言编写的复杂代码之后，为什么不添加友好而易懂的英语的描述性简明注释来解释代码的操作呢？ 有人会说“代码不难理解”，“使函数变小”，“使用描述性名称”，“不要编写意大利面条式代码”。 但是我们都知道这还不够。这些仅是准则-重要且有用的准则- 但它们并不能改变某些算法很复杂的事实。因此在逐行阅读它们时很难理解。 用一些关于它的一般操作的注释来解释一个复杂的算法真的很糟糕吗？用注释解释复杂的代码有什么问题？

236 programming-practices  documentation  comments 

我被特别要求我逐行（或适当地-例如逐个图像等）给出我的老板希望能够阅读和遵循的解释或评论。 由于他不是程序员，所以他无法遵循代码，因此希望将其全部翻译成英文。 有人被要求这样做吗？ 我已经对所有源代码进行了评论，并使用JSDoc生成了所有函数，变量等的完整文档，并包括一个实现示例和完整的带有演示的演示程序。 我还能为非程序员注释代码吗？ 这不是一个合理的要求，对吗？ 更新 最后，我设法解释了为什么没有充分利用时间来完成他的要求。他是一个理性的人，只是对我的工作不了解。一旦他看到了这个帖子，我想他很快就会明白这不是正常的要求。 我确实提供了适合其他程序员遵循的文档（JSDoc和内联注释-以及有关技术问题的一些附加说明），以及该程序主要逻辑的非常宽泛的流程图，供老板参考。 最后，各方都感到满意，我们继续前进。

155 documentation 

RFC 2606标准保留了example.org，example.net和example.com域名，以用作文档中的示例。 可以用作示例的电话号码（包括国家代码）的等效项是什么，例如，为用户提供以哪种格式输入电话号码的示例？ 在最佳情况下，它将是由相关标准指定的虚拟号码作为示例电话号码，并且不会归属于任何真实订户。

112 documentation  standards  help-documentation 

假设我正在开发一个相对较大的项目。我已经用Doxygen记录了我的所有类和函数，但是，我有个主意，在每个源代码文件上都写上“程序员笔记”。 这背后的想法是用通俗的术语解释一个特定的类是如何工作的（不仅是为什么大多数评论如此）。换句话说，让其他程序员对类的工作方式有另一种看法。 例如： /* * PROGRAMMER'S NOTES: * * As stated in the documentation, the GamepadManager class * reads joystick joystick input using SDL and 'parses' SDL events to * Qt signals. * * Most of the code here is about goofing around the joystick mappings. * We want to …

104 documentation  large-scale-project 

在有关从最新版本回滚第三方SDK的会议中，我们注意到开发人员已经在提交历史记录中标记了不应使用最新版本。 一些开发人员认为这是一种不好的做法，应该在源文件（即// Don't upgrade SDK Version x.y.z, see ticket 1234）或项目级别的README文件中进行注明。其他人则认为，由于提交历史记录是项目文档的一部分，因此对于此类信息而言，它是可接受的位置，因为无论如何我们都应该阅读它。 应该使用提交历史记录将关键信息传达给其他开发人员，还是应该将这些信息复制到其他位置（例如项目README或相关源文件中的注释）？

94 version-control  documentation 

我正在做一个相当大的项目，并承担了为它做一些翻译的任务。有很多标签没有被翻译，当我浏览代码时，我发现了这小段代码 //TODO translations 这让我想到了对自己（和其他人？）的这些评论的意义，因为我感觉到大多数开发人员在完成某些代码后，就会按照原本应该做的去做，直到他们拥有完为止进行维护或添加新功能。因此，这TODO将丢失很长时间。 编写此注释是否有意义，还是应该将其写在白板/纸上/其他仍以开发人员为重点的地方？

86 documentation  comments 

我写了以下代码： if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } 这里有一个注释行。但是我认为，通过使if和之间的区别显而易见，可以使代码更清晰else。颜色突出显示的差异更加明显。 这样的代码注释掉是个好主意吗？

83 documentation  comments 

首先，在这个问题上，我想避免争论源代码注释是好是坏。我只是想更清楚地了解人们在谈论可以告诉您原因，原因或方式的评论时的意思。 我们经常看到诸如“注释应该告诉您为什么；代码本身应该告诉您如何”之类的准则。很容易就抽象的观点达成一致。但是，人们通常会像教条一样掉下来，离开房间而无需进一步解释。我已经看到它在许多不同的地方和环境中使用过，看起来人们可以就流行语达成共识，但是他们似乎完全是在谈论不同的事情。 因此，回到问题所在：如果评论可以告诉您原因，那么我们在说什么呢？这就是为什么这段代码首先存在的原因吗？这是片段代码应该做什么？如果有人可以给出清楚的解释，然后添加一些好的示例，我将不胜感激（确实不需要坏的示例，但是可以随意添加它们以进行对比）。 关于评论是好是坏，有很多问题，但是没有人能解决一个具体问题，即什么是可以告诉您为什么的好的评论示例。

78 documentation  comments 

三个月前，我正在做一个项目，然后突然出现了另一个紧急项目，我被要求转移我的注意力。 从明天开始，我将回到旧项目。我意识到我不记得自己在做什么。我不知道从哪里开始。 我该如何记录一个项目，这样无论何时回头，离我离开任何地方都不会花费我几分钟的时间。有最佳做法吗？

72 project-management  documentation 

我打算离开目前的工作，因为我们被限制在平庸的共享主机上使用Blub和企业Blub框架以及Blub级别的Web服务器。我的同事很友善，我的老板是普通的小企业主-我想完全出于技术原因离开。我觉得被Blub浸透对我的大脑有害，并使我成为一个更糟糕的程序员。 当我离开时，如何向老板和同事解释？如何有效表达对Blub的投诉？我可以向我的继任者提供什么样的警告？ （试图确保我符合标准）

66 career-development  documentation 

我了解文件齐全的代码的重要性。但是我也了解自我记录代码的重要性。直观地读取特定功能越容易，我们在软件维护期间就可以进行得越快。 话虽如此，我喜欢将大型功能分离为其他较小的功能。但是我这样做的程度是，一个班级最多可以有五个班级，以服务于一种公共方法。现在将五个私有方法乘以五个公共方法，您会得到大约二十五个隐藏方法，这些隐藏方法可能只会被那些公共方法调用一次。 当然，现在可以更轻松地阅读这些公共方法，但是我不禁认为，拥有太多函数是不明智的做法。 [编辑] 人们一直在问我为什么认为过多的功能是不好的做法。 简单的答案：这是一种直觉。 我的信念一点都没有任何小时的软件工程经验作为后盾。只是不确定性给了我一个“作家的障碍”，但对于程序员而言。 过去，我只编写个人项目。就在最近，我开始进行基于团队的项目。现在，我想确保其他人可以阅读和理解我的代码。 我不确定会提高可读性。一方面，我正在考虑将一个较大的功能分成名称可理解的其他较小的功能。但是我还有另一面说这是多余的。 因此，我要对此进行启发以选择正确的路径。 [编辑] 下面，我包括我怎么两个版本可以解决我的问题。第一个解决方案是不分离大块代码。第二个做不同的东西。 第一版： public static int Main() { // Displays the menu. Console.WriteLine("Pick your option"); Console.Writeline("[1] Input and display a polynomial"); Console.WriteLine("[2] Add two polynomials"); Console.WriteLine("[3] Subtract two polynomials"); Console.WriteLine("[4] Differentiate two polynomials"); Console.WriteLine("[0] Quit"); } 第二版： public static int …

63 programming-practices  code-quality  documentation 

可以使用多种工具来自动生成文档，其中GhostDoc是其中最著名的一种。但是，根据定义，它生成的所有内容都是多余的。它查看方法，类等的名称，并输出可能更详细地解释它们的英语。在最好的情况下，它可以完成读者头脑中已经可以做的事情（示例取自此处）： /// <summary> /// Initializes a new instance of the <see cref="Person"/> class. /// </summary> public Person() ... 在最坏的情况下，它最终可能会生成奇怪的文档，而这些文档实际上在试图启发性地弄清名称的含义时具有误导性： /// <summary> /// Riches the text selection changed. /// </summary> /// <param name="richTextBox">The rich text box.</param> private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ... 似乎对GhostDoc的态度是，“本质上来说，拥有某种形式的 XML文档会更好”，但是当该文档100％冗余时，为什么呢？充其量只是在浪费大量的空间吗？ 在我的工作场所，我们几乎必须始终使用GhostDoc的自动生成的文档来记录所有内容。您这样做是不是有合理的理由，如果您不想自己亲自编写文档，则不要简单地将代码保留在文档之外？

60 documentation  automation  automatic-programming 

我正在编写用户文档（SOP），其中涉及我试图很好描述的第三方程序。一个这样的程序是服务器，除了在初始化/启动例程期间显示的图形外，它几乎不提供启动指示。 作为开发人员，我已将该窗口用作状态快速指示符，并希望将其传达给我的听众（操作员/工程师），但我不知道它叫什么。我的第一个问题是启动时显示的图形是否有正式名称或广泛接受的名称（以下示例）。第二，什么是更可取的引用方式，可以快速将想法（没有图形）传达给我的听众？ 例子 |

59 documentation  component  jargon 

有时，我遇到的情况是我正在编写的部分代码是（或似乎是）不言而喻的，其名称基本上会作为注释重复： class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation { get; set; }; } （C＃示例，但请将该问题与语言无关）。 这样的评论是没有用的。我究竟做错了什么？是错误的名称选择吗？我怎样才能更好地评论这样的部分？我应该跳过诸如此类的评论吗？

54 programming-practices  documentation  language-agnostic 

当您使用jsdocs之类的工具时，它会根据代码中的注释在代码库中生成静态HTML文件及其样式。 应该将这些文件检入Git存储库中，还是应该使用.gitignore忽略它们？

49 git  documentation