Questions tagged «documentation»

为什么某些语言的文档说“等于”而不是“是”？ 例如，Python文档说 itertools.chain(*iterables) ... 等效于： def chain(*iterables): # chain('ABC', 'DEF') --> A B C D E F for it in iterables: for element in it: yield element 或者，这个C ++参考的find_if： 该功能模板的行为等效于： template<class InputIterator, class UnaryPredicate> InputIterator find_if (InputIterator first, InputIterator last, UnaryPredicate pred) { while (first!=last) { if (pred(*first)) return first; …

23 c++  python  documentation  compiler 

已关闭。这个问题需要更加集中。它当前不接受答案。 想改善这个问题吗？更新问题，使其仅通过编辑此帖子来关注一个问题。 去年关闭。 我想记录我的代码，以使几个月后再次阅读和浏览代码的需求降至最低。 我知道有不同类型的文档（在源代码中和外部，序列图等中）。 我只想知道什么是记录我的代码的有效方法，所以几个月后我想看我的代码时，我花更少的时间在阅读代码和理解代码流上。

22 documentation  code-reviews  documentation-generation  help-documentation 

关于所有内容的记录似乎有点争议，包括字段的getter和setter的“ JavaBean”语法：人们说它的DRY不必要地冗长而重复，打破了DRY（不要重复自己），命名约定应该解释一切，并且会使代码/文档混乱。有时这些论点起作用。但有时，您最终会遇到以下情况： 上面大胆遵循这些原则的开源项目很常见。您剩下的都是完全没用的文档。但这并不能解释下面的情况，可能的影响，甚至是预期的值（是null还是永不null？我不知道； Javadoc不会告诉我）。 那我什么时候应该记录？即使偶尔会使代码混乱，我是否也要记录所有内容？还是我没有记录任何东西，因为在我看来这是“显而易见的”？

22 documentation 

我无法数出“单元测试是被测代码文档的重要来源”这一类读语句的次数。我不否认他们是真实的。 但就我个人而言，我从来没有发现自己将它们用作文档。对于我使用的典型框架，方法声明记录了它们的行为，而这就是我所需要的。我假设单元测试将备份该文档中所述的所有内容，并可能还会添加一些其他内部内容，因此，一方面它会复制文档，而另一方面可能会添加一些不相关的内容。 所以问题是：什么时候将单元测试用作文档？什么时候评论不能涵盖所有内容？通过开发人员扩展源代码？他们公开了哪些文档本身无法公开的有用和相关的内容？

22 unit-testing  documentation 

我们目前正在以两列格式编写功能和技术规范；摘要句子和技术细节。细节通常是指带有图表，布局设计等的附录。 但是我正在努力用什么时态来写它： 以过去的时态好像工作已经完成了，我努力地展示出现有工作的重点扩展。需要完成的将来时态X听起来很像一个待办事项列表或时态中立，因为它要么已经完成，要么已经完成。 更进一步的混淆是，英语不是第一语言的人们可能会阅读本规范。

21 documentation  specifications  writing 

背景： 我和我的合作者正在为学术期刊撰写文章。在研究过程中，我们用Java编写了一个仿真程序。我们想让仿真程序免费供其他人使用。我们已决定将代码托管在GitHub存储库上。为了使其他人易于使用，我们希望为程序编写良好的文档，包括： 每个类和方法的Javadocs 如何使用代码 描述代码的高级结构 我的高级问题是： 您能否提供一个可以用来描述程序高级结构的单词和图表的好例子？ 这包括作为子问题： 我们如何显示哪些包中包含哪些类？ 我们如何显示哪些软件包依赖于其他软件包？ 我们如何显示程序中的对象/类如何协同工作？ 我们已尝试在代码设计中使用领域驱动的设计原则。我们如何显示域中的对象与编码这些对象的特定源代码文件之间的对应关系？（请参阅下面我对项目的“通用语言”说明。） 到目前为止我做了什么 无处不在的语言 我们将代码的“普遍语言”描述放在文件中ubiquitous-language.md，内容如下。 该项目的目的是研究在不同的提前期模型，报告延迟和需求模型下，补货策略在具有单个设施的简单供应链中的执行情况。 在每个期间，发生以下事件： 如果计划在当前期间将货物运送到工厂，则工厂的库存水平将增加X单位。 如果计划表指示当前期间为报告期，则工厂将向 供应商提交报告。该供应商可能会收到报告 瞬间，或者几个星期的延迟，由指定的时间表。 如果供应商已收到报告，则根据 补货策略，它将计算X单位的补货数量。一个出货的产品的X单位将被安排升周期的筹备时间之后抵达。 客户到达工厂并需要X单位的产品。任何未满足的需求都会丢失。 源代码结构 我们在structure.md下面的文件中放置了不完整的代码“高级”描述。 包装等级结构 在最高级别，源代码分为三个包 com.gly.sfs 该main方法的主类位于此程序包中。 com.gly.sfs.model 域模型类驻留在此程序包中。 com.gly.sfs.util 帮助程序类驻留在此程序包中。

20 java  documentation 

所以我们有一个像这样的界面 /// <summary> /// Interface for classes capable of creating foos /// </summary> public interface ICreatesFoo { /// <summary> /// Creates foos /// </summary> void Create(Foo foo); /// <summary> /// Does Bar stuff /// </summary> void Bar(); } 最近，我们播放了一个文档故事，涉及生成并确保像上面那样有大量XML文档。但是，这导致了很多重复的文档。示例实现： /// <summary> /// A Foo Creator which is fast /// </summary> …

20 c#  documentation  xml  documentation-generation 

已关闭。这个问题是基于观点的。它当前不接受答案。 想改善这个问题吗？更新问题，以便通过编辑此帖子以事实和引用的形式回答。 6年前关闭。 在使用WordPress和BuddyPress为我花了一年多的时间为我工作的社交网络项目之后，我的程序员消失了，即使他在整个期间每周都得到报酬。是的，他还没有死，因为我使用电子邮件跟踪器进行确认并看到他打开了我的电子邮件，但是他没有回应。看来他找到了另一份工作。我不知道他为什么不能这么说。我什至还付了他未完成的工作预付款。 问题在于，我从来没有要求他编写过的大多数功能的完整文档。在过去的1年中，有很多功能，其中一些功能仍然无法修复。现在看来一切令人困惑。 我现在应该做的第一件事是什么？我该如何进行？ 我想要做的第一件事就是找到另一个程序员，但是我想从头开始，将所有当前代码记录在案，以便任何程序员都可以毫无问题地使用所有功能。 那是我应该做的第一件事吗？如果是，我该怎么办？ 此类文件所需的标准文档类型是什么？我可以让一名程序员来为所有代码做文档并修复错误，还是文档不是很重要？ 另外，您认为让另一个“个人”程序员更好还是让一家为他们工作的程序员更好的公司，这样如果分配给我的项目的程序员消失了，另一个人可以代替他，而无需我的参与？我觉得这是我一开始应该采取的方法。

19 documentation  hiring  outsourcing  knowledge-transfer  wordpress 

有时，尽管不是经常，但我必须在代码中包含数学逻辑。所使用的概念大多非常简单，但是生成的代码却不是-许多目的不明确的变量，以及某些意图不那么明显的操作。我的意思并不是说代码不可读或不可维护的，只是它的waaaay难度比实际的数学题理解。我尝试评论最难理解的部分，但存在与仅对其进行编码相同的问题- 文本不具有数学的表达能力。 我正在寻找一种更有效且易于理解的方式来解释某些复杂代码（最好是代码本身）背后的逻辑。我考虑过TeX-编写文档并将其与代码分开生成。但是然后我必须学习TeX，并且文档本身也不会包含在代码中。我想到的另一件事是对写在纸/白板上的数学符号，方程式和图表进行拍照，并将其包含在javadoc中。 有没有更简单明了的方法？ PS给变量赋予描述性名称（timeOfFirstEvent而不是t1）实际上会使代码更冗长，甚至更难阅读。

19 java  documentation  math 

最近，我一直在努力重构当前正在处理的部分代码库-不仅可以自己更好地理解它，而且还可以使其他从事代码工作的人更容易理解。 我倾向于认为自记录代码很好。我只是认为它更干净，并且如果代码能说明一切，那 ... 很好。 另一方面，我们有诸如javadocs之类的文档。我也喜欢这个，但是这里的评论（当然还有一般的评论）也有过时的风险。但是，如果它们是最新的，那么理解复杂的算法就非常有用。 最佳做法是什么？您如何在自我说明代码和javadocs之间划清界限？

18 java  documentation  refactoring  javadocs 

已关闭。这个问题是基于观点的。它当前不接受答案。 想改善这个问题吗？更新问题，以便通过编辑此帖子以事实和引用的形式回答。 5年前关闭。 每个人都知道，有据可查的软件开发会带来成功。但是，这通常意味着文档中不仅会涉及纯文本，而且还会涉及二进制内容，例如UML图。我听说很多人都这么说。版本控制系统不适用于二进制文件。我完全理解并同意这个问题。我问了几个经验丰富的开发人员，最好的存储文档的位置应该在哪里，而我得到的答案是“ wiki”。Wiki很好，但是我考虑了另一个潜在的问题。存储在版本控制系统中的源代码如何连接到Wiki中的相关文档？假设有人克隆了git或mercurial的存储库。他/她如何轻松找到文件？还是我只是错过了什么？ 我知道某些Wiki系统具有与源代码控制系统集成的能力。但是我关心的不是集成能力。如果您已经从git仓库中克隆了源代码，并且过了一会儿，那么您将在火车上并希望继续在火车上离线工作（这是DVCS的一大功能）。然后您突然意识到，由于您在火车上离线工作，因此您无权访问文档。另一方面，如果文档存储在git存储库中，则可以访问克隆了存储库的文档。

18 documentation  wiki 

假设您是唯一一名辞职的开发人员。您应该在代码本身之外创建什么样的信息/材料并留下来替换？ 显而易见的答案是“肯定会想得到一份新工作”，但是距我开始新工作已经有一段时间了，而我忘记了当时最需要的最重要的东西。 我在想： 帐号/密码 设备，备份，软件CD的位置 还有什么？

18 documentation  knowledge-transfer 

我们团队中的一位开发人员认为，有必要为方法签名中的每个参数编写一个Javadoc注释。我认为这不是必要的，实际上我认为这甚至是有害的。 首先，我认为参数名称应具有描述性和自我记录性。如果您的参数的用途不是很明显，那么您可能做错了。但是，我确实知道，有时不清楚参数的用途，因此在这种情况下，应该编写一个Javadoc注释来解释该参数。 但是我认为没有必要对每个参数执行此操作。如果该参数的作用已经很明显，则javadoc注释是多余的；您只是为自己创造了额外的工作。此外，您还为需要维护代码的任何人创建了额外的工作。方法会随着时间而变化，维护注释几乎与维护代码一样重要。您有多少次看到“ X是Y导致Z原因”这样的注释，只是看到该注释已过时，实际上该方法甚至不再使用X参数？它总是发生，因为人们忘记了更新评论。我认为，误导性评论比根本没有评论更具危害性。因此存在过度注释的危险：通过创建不必要的文档，您可以 但是，我尊重团队中的另一个开发人员，并接受他也许是对的，但我错了。这就是为什么我会向其他开发人员提出您的问题：确实有必要为每个参数编写一个Javadoc注释吗？在此假设该代码是我公司内部的代码，任何外部方都不会使用。

18 java  documentation  source-code  comments  maintainability 

我一直在研究如何更正式地记录软件项目，并且了解了IEEE 830-1998：《软件需求规范的推荐做法》。但是，从该链接可以看到，它已被取代。 我知道830-1998，甚至830-1993都可以使用。但是，如果没有别的，我想知道是什么标准取代了它。在这种情况下，可能没有关系，但是如果为了其他技术问题而取代了其他标准，我认为最好在某个地方链接取代的另一个标准（如果不是同一行中的另一个标准的话（830，在本指南中）案件））。 值得一提的是： 在IEEE标准协会网站上搜索“软件要求规范”或“软件要求”时，最新标准为830-1993， SWEBOK的2004年（当前）版本引用了830-1993（第2.5段）， 该文档的Wikipedia文章并未提及该标准已被取代。 TLDR：您如何找到取代另一标准的标准，以及取代830-1998的标准？

17 documentation  requirements  standards 

我们都看到了无数带有“最低系统要求”的软件示例，如下所示： Windows XP / Vista / 7 1GB内存 200 MB储存空间 一般如何确定这些？显然，有时会有特定的限制（如果程序在磁盘上占用200 MB，则这是一个硬要求）。除了那些情况之外，对于RAM或处理器之类的东西很多次都发现，没有硬性约束的情况下，更多/更快更好。如何确定这些？开发人员只是编造看起来合理的数字吗？质量检查人员是否经过严格的流程测试，以测试各种要求，直到找到性能可接受的最低设置？我的直觉说应该是后者，但实际上通常是前者。

17 documentation  requirements  qa