comments - 写评论时将类型设为复数的好方法是什么？

Question

在写评论时，我有时发现自己在写评论时需要用复数形式谈论类型(类、结构等)，例如:

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

问题是，类型名称是单数(即 Thing )，但我想在评论中以复数形式谈论它们。

如果我说 Things ，它向读者暗示它正在谈论一种名为 Things 的类型。 ，事实并非如此。如果我说 Thing's ，它看起来很尴尬，因为它在语法上不正确(它要么是所有格，要么是“Thing is”，而不是复数)。我可以围绕这个问题说 a list of Thing items
编写复数类型时要坚持的良好约定是什么？

Answer 1

好吧，根据您使用的文档系统，您可以用特殊语法包装类型的名称并将 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.

不是 100% 确定 doxygen 变体，但它应该是这样的。

如果你没有使用特定的文档系统，因此没有特别的评论，我会做这样的事情:

Get a list of [Thing]s from somewhere.

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