Question

这是一个与语言无关的问题，但我在人们喜欢的可读性和可维护性方面徘徊......我的假设情况是我正在编写一个函数，给定一个序列将返回一个包含所有重复元素的副本删除并撤销订单。

/*
*This is an extremely well written function to return a sequence containing 
*all the unique elements of OriginalSequence with their order reversed
*/    
ReturnSequence SequenceFunction(OriginalSequence)
{...}

OR

UniqueAndReversedSequence MakeSequenceUniqueAndReversed(OriginalSequence)
{....}

以上假设是一个清晰的例子，在第一个实例中使用注释或在第二个实例中使用非常详细的函数名来描述函数的操作。

干杯，

理查德

Answer 1

我更喜欢详细的函数名称，因为它使调用站点更具可读性。当然，一些函数名称（如您的示例）可能会变得非常长。

也许您的示例函数的更好名称是ReverseAndDedupe。哦，现在我们更清楚一点，我们有一个有两个职责的职能*。也许将它分成两个函数会更好：Reverse和Dedupe。

现在，呼叫站点变得更具可读性：

Reverse(Dedupe(someSequence))

* 注意 ：我的经验法则是，名称中包含“和”的任何函数都有太多责任，需要拆分为分开功能。

Answer 2

就我个人而言，我更喜欢第二种方式 - 从函数名称很容易看出它的作用 - 并且因为函数内部的代码编写得很好，所以很容易弄清楚其中发生了什么。

我发现评论的问题是它们很快就会过时 - 没有编译时检查以确保您的评论是正确的！

此外，您无法访问实际调用该函数的位置的注释。

虽然是一个主观的问题！

Answer 3

理想情况下，你会将两者结合起来。尽量保持你的方法名称简洁但足够描述，以便更好地了解它将要做什么。如果方法名称有可能缺乏明确性，那么您应该有评论来帮助读者理解逻辑。

Answer 4

即使使用描述性名称，您仍应简明扼要。我认为你在这个例子中所拥有的就是矫枉过正。我会写的

UniqueSequence Reverse(Sequence)

Answer 5

我可能会做其中一个：

将其称为ReverseAndDedupe（或DedupeAndReverse，具体取决于它是哪一种 - 我希望Dedupe单独保留第一次出现并丢弃以后出现的那些，所以两个操作不通勤）。所有函数都使某些后置条件为true，因此Make当然可以缩短过长的名称。通常不需要为它们所操作的类型命名函数，如果它们是，那么它应该是一致的格式。因此，Sequence也可能会从您提议的名称中移除，或者如果不能，那么我可能会将其称为Sequence_ReverseAndDedupe。
根本不创建此功能，请确保来电者可以Reverse(Dedupe(x))或Dedupe(Reverse(x))，具体取决于他们实际需要的内容。它们不再需要编写代码，因此只有一个问题是，是否有一些狡猾的优化仅适用于同时执行这两项操作的情况。避免使用中间副本可能符合要求，但一般的观点是，如果你不能简明地命名你的功能，请确保它有很好的理由为什么它会做很多不同的事情。
如果它返回原始序列的副本，则将其称为ReversedAndDeduped - 这是我从Python中获取的一个技巧，l.sort()对列表l进行排序，并且sorted(l)根本不会修改列表l。
为其指定一个特定于其所用域名的名称，而不是试图使其如此通用。 为什么我是否正在重复和撤消此列表？可能有一些术语表示该状态中的列表，或者某些功能只能在这样的列表上执行。所以我可以称它为'Renuberate'（因为一个反向的，重复删除的列表被称为“Renuberated形式的列表”，或'MakeFrobbable'（因为Frobbing需要这种格式）。

我也对它进行评论（或更好，文档它），以解释它保证的重复数据删除类型（如果有的话） - 可能是免费的实现删除它喜欢的任何欺骗，只要它能得到它们。）

我不会评论它“写得非常好”，虽然我可能会评论“高度优化”意味着“这段代码真的难以使用，但就像拍板一样，请不要在没有运行的情况下触摸它” em> all 性能测试“。

我认为我不想使用5个字的功能名称，尽管我希望我过去。

Answer 6

我评论哪里有解释，以便描述性名称无法充分传达。如果有一个图书馆的特殊性迫使我做一些看起来非标准的东西，或者在内联评论中有价值，我会这样做，但除此之外，我依靠名称很好的方法，不要评论很多东西 - 除了我正在编写代码，而这些代码适用于我自己。一般情况下，它们会被删除。

一般来说，函数头注释只需维护更多行，并要求读者查看注释和代码，然后确定哪些是正确的，如果它们不对应。显然事实总是在代码中。注释可能会说X但注释不会编译到机器代码（通常），所以...

必要时进行评论并养成将事物命名的习惯。这就是我的工作。

我应该写更多描述性的功能名称还是添加评论？

6 个答案: