How should documentation refer to the plural of a type name?
In commenting or documenting code, I often find it useful to refer to the plural of a type's name, but I am unsure what is the most readable and least ambiguous way to do this. For instance, if I have a class named Dog, it might seem natural to say "All Dogs have woof() methods". But what if I also have a class named "Dogs" that can contain multiple instances of type Dog. Is it confusing to say "Dogs" in reference to multiple things of type Dog as opposed to a single thing of type Dogs?
Note that I am not asking what the type naming convention should be, but how to refer to the type in comments or documentation external to the code.
I have found English grammar rules that sometimes allow 's to be used in forming a plural. For instance, "Do's and Don'ts", or "I got all A's", but it doesn't look right to me to say "All Dog's have woof() methods". This may seem like a silly question, but it has caused me grief many times over the years.
This is clearly opinion based, but I'd consider all Dogs have very confusing. I'd much rather see the class name typeset differently or quoted somehow, eg, all 'Dog's have or, if room allows, the still clearer (and easier to read) all Dog instances have .
Approaching this from a linguistic angle, I would expect a simple apostrophe to suffice. For example, according to the Chicago Manual of Style the rules for plurals of letters are as follows:
Capital letters used as words, numerals used as nouns, and abbreviations usually form the plural by adding s. To aid comprehension , lowercase letters form the plural with an apostrophe and an s .
Extrapolating that in the case of ambiguity an apostrophe is allowed, this seems to me to be a grammatically correct solution. For example, multiple instances of the letter A would also be called A's.
Also, some argue using the apostrophe for possession would be undesirable either way, so there would be no real confusion if you never refer to Dog's in the possessive form:
So, in all, "The car's antenna" is fine, "The antenna of the car" would still be favoured by some, and "Its antenna" is also fine, though the KJV would have used "the antenna thereof".
It might be worthwhile asking this on English Stack Exchange. From a quick look around most grammatical rules on plurals are rather specific (eg, names of people) and do not apply directly to class names.
链接地址: http://www.djcxy.com/p/14948.html上一篇: 独特（）与lambda？
下一篇: 文档应该如何引用类型名称的复数形式？