开发者

What's a good way to make a type a plural when writing comments?

When writing comments, I sometimes find myself needing to talk about a type (class, struct, etc.) in plural when writing comments, such as:

/*
 * getThings
 *    Get a list of --> Things <-- from somewhere.
 */
Thing *getThings(void);
开发者_高级运维

The problem is, the type name is singular (namely, Thing), but I want to talk about them in plural in comments.

If I say Things, it suggests to the reader it's talking about a type called Things, which is not the case. If I say Thing's, it looks awkward because it's not grammatically correct (it's either possessive or "Thing is", not plural). I could talk around the problem and say a list of Thing items

What's a good convention to stick to when writing plurals of types?


Well, depending on the documentation system you're using, you can wrap the name of the type in a special syntax and put the s outside it. For example:

.NET XML comments

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

doxygen C/C++ comments

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

Not 100% certain on the doxygen variant but it should be something like that.

And if you're not using a particular documentation system and thus have no special comments, I'd do something like:

Get a list of [Thing]s from somewhere.

Or you could use ( ) or { }, depending on preference...


I would use the 's' in parentheses.

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

上一篇:

下一篇:

精彩评论

暂无评论...
验证码 换一张
取 消

最新问答

问答排行榜