我正在研究“意大利面条代码”项目，并且在修复错误和实现新功能的同时，我还进行了一些重构，以使代码可以进行单元测试。 这些代码通常紧密耦合或非常复杂，以至于修复一个小错误将导致许多类被重写。因此，我决定在代码中停止重构的位置画一条线。为了清楚起见，我在解释这种情况的代码中添加了一些注释，例如： class RefactoredClass { private SingletonClass xyz; // I know SingletonClass is a Singleton, so I would not need to pass it here. // However, I would like to get rid of it in the future, so it is passed as a // parameter here to make this change …
当我为自己编写小型脚本时，我会将代码和注释高度堆积在一起（有时注释比代码更多）。我要说的很多人都说，即使这些脚本是个人的，我也应该记录这些脚本，以便如果我确实出售它们，我将做好准备。但是注释不是文档形式吗？ 这不是吗： $foo = "bar"; # this is a comment print $foo; # this prints "bar" 被视为文档，特别是如果开发人员正在使用我的代码？还是认为文档不在代码本身之外？
我曾经是要求XML注释用于文档的爱好者。从那以后，我改变了主意，主要有两个原因： 像好的代码一样，方法应该是不言自明的。 实际上，大多数XML注释都是无用的噪声，不会提供任何附加值。 很多时候，我们只是使用GhostDoc生成通用注释，这就是我所说的无用噪声： /// <summary> /// Gets or sets the unit of measure. /// </summary> /// <value> /// The unit of measure. /// </value> public string UnitOfMeasure { get; set; } 对我来说，这很明显。话虽如此，如果要包含特殊说明，那么我们绝对应该使用XML注释。 我喜欢这篇文章的摘录： 有时，您将需要写评论。但是，这应该是例外而不是规则。仅当注释表示无法用代码表达的内容时，才应使用注释。如果要编写简洁的代码，请努力消除注释，而改写自记录代码。 我认为我们仅应在代码不足以自行解释时使用XML注释吗？ 我相信这是一个很好的示例，其中XML注释使漂亮的代码看起来很难看。需要上这样的课... public class RawMaterialLabel : EntityBase { public long Id { get; set; } …
我是正确编写代码的支持者，并且我很清楚其可能存在的弊端。这超出了这个问题的范围。 考虑到我在Visual Studio中非常喜欢IntelliSense，我喜欢遵循为每个公共成员添加XML注释的规则。 但是，存在一种形式的冗余，即使像我这样的过多评论者也会对此感到困扰。以List.Exists（）为例。 /// <summary> /// Determines whether the List<T> contains elements /// that match the conditions defined by the specified predicate. /// </summary> /// <returns> /// true if the List<T> contains one or more elements that match the /// conditions defined by the specified predicate; otherwise, false. /// …
为equals，compareTo等广为人知的方法编写注释是否是一种好习惯？ 考虑下面的代码。 /** * This method compares the equality of the current object with the object of same type */ @Override public boolean equals(Object obj) { //code for equals } 我的公司非常想输入上述注释。是否需要上述Javadoc注释？equals方法之类的方法（compare，compareTo）等不是很明显并且很好理解吗？ 您有什么建议？
我正在阅读Robert C. Martin的Clean Code，该短语TILT在某些代码示例中莫名其妙地出现。示例（顺便说一下，它是在Java中）： ... public String errorMessage() { switch (status) { case ErrorCode.OK: // TILT - Should not get here. return ""; case ErrorCode.UNEXPECTED_ARGUMENT: return "Unexpected argument"; case ErrorCode.MISSING_ARGUMENT: return "Missing argument"; ... } ... 从上下文来看，我猜测是TILT指定一个无法访问的状态，并且仅包含该状态以满足编译器的要求（例如，在上面的代码中，TILT出现这种ErrorCode.OK情况是因为如果状态为OK，则不会出现错误消息），但是我不确定。 有人知道TILT代表/意味着什么吗？
这可能是一个愚蠢的问题，但是已经出现了一段时间，在其他任何地方都找不到合适的答案。 我有一位老师说，即使只有一个，我们也应该明确列出每个参数的描述。这导致很多重复： double MyFunction(const int MyParam); // Function: MyFunction // Summary: Does stuff with MyParam. // Input: int MyParam - The number to do stuff with. // Output: MyParam with stuff done to it. 在编写代码文档时，您有多详细？