在撰写评论时,将复数形式设为复数是一种好方法？

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.

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