写注释时如何将类型变成复数的好方法是什么？

Question

写注释时如何将类型变成复数的好方法是什么？

7

在编写注释时，我有时需要在注释中使用复数形式来谈论类型（类、结构体等），例如：

/*
 * getThings
 *    Get a list of --> Things <-- from somewhere.
 */
Thing *getThings(void);

问题在于，类型名称是单数形式（即Thing），但我想在注释中使用复数形式来谈论它们。

如果我说Things，读者会认为它是在谈论一个名为Things的类型，这并不是事实。如果我说Thing's，它看起来很尴尬，因为语法上不正确（它可以是所有格或“Thing is”，而不是复数）。我可以绕过这个问题，并说一系列Thing项目。

在编写类型的复数形式时，有什么好的约定可遵循？

- Joey Adams

2个回答

1

我会在括号中使用“s”。

/* Get a list of Thing(s) from somewhere */

- Ido Weinstein

我也考虑过这个问题。但是，再想一想，我认为这样做会变得很烦人，就像Yoda条件一样，例如if (5 == count)或者在英语中说“她或他”。这些都是让我分心并且讨厌作者坚持倒退思维的事情，而这实际上并没有帮助到任何事情。尽管如此，还是点赞。无论如何，回答我的问题似乎很难避免这种情况。 - Joey Adams

我同意，如果像Yoda条件一样经过一段时间后读起来会很烦人（我喜欢那个短语），但是与自然语言的任何不自然变化一样。 - Ido Weinstein

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Jake Petroules · Accepted Answer

根据您使用的文档系统，您可以在特殊语法中包装类型名称并将s放在其外部。例如：

.NET XML注释

Get a list of <see cref="Thing"/>s from somewhere.

Doxygen C/C++注释

Get a list of \link Thing \endlink s from somewhere.

我不完全确定Doxygen的变体，但应该类似于这样。

如果您没有使用特定的文档系统，因此没有特殊的注释，我会这样做：

Get a list of [Thing]s from somewhere.

或者您可以使用 ( ) 或 { }，具体取决于个人喜好...