If the class name cannot be converted into proper English, while retaining it’s sense, then that’s usually indicative of bad class naming. That is, if you’re talking about a ShippingMethodRepository, then there’s rarely a reason not to write “shipping-method repository” and thus “shipping-method repositories”. This is easier for most people to read, because of the subtle visual clues in compound modifiers and such.
In the few cases where you feel a need to point to the class-name, if you give each situation some thought, you’ll probably find that you’re missing either the word “instance” or “class” in your sentence. I suggest putting it back in as a matter of course — it is easy to cause confusion by not being specific.
As a bonus, this will make it easier to pluralise. ie. “ShippingMethodRepository instance” becomes “ShippingMethodRepository instances”. (You’ll probably find that you never need to pluralise class in this context.)
how to pluralize ‘special’ terms e.g. class names
Quite often I find myself referring in text to objects which have strict naming conventions e.g. Java objects, processes, services. I find myself in a dilemma over how to pluralize these names.
It seems wrong to pollute the meaningful name by adding an ‘s’ – or worse, a plural that modifies the rest of the name like SomethingUtility -> SomethingUtilities. What if someone does a text search looking for the name? Or cuts and pastes from my comment to search through a log file?
I have sometimes resorted to an ungrammatical apostrophe, but this can confuse plural with ownership.
Is there any better solution?
4
If the class name cannot be converted into proper English, while retaining it’s sense, then that’s usually indicative of bad class naming. That is, if you’re talking about a ShippingMethodRepository, then there’s rarely a reason not to write “shipping-method repository” and thus “shipping-method repositories”. This is easier for most people to read, because of the subtle visual clues in compound modifiers and such.
In the few cases where you feel a need to point to the class-name, if you give each situation some thought, you’ll probably find that you’re missing either the word “instance” or “class” in your sentence. I suggest putting it back in as a matter of course — it is easy to cause confusion by not being specific.
As a bonus, this will make it easier to pluralise. ie. “ShippingMethodRepository instance” becomes “ShippingMethodRepository instances”. (You’ll probably find that you never need to pluralise class in this context.)
0
In my
Documentations, I do it like we do it here on Stackexchange and use different fontStyles for specialTerms.For those terms where a different pluralization would be required according to English grammar, I just don’t do it. My excuse for this is that the names of my
Classs are not English words. They are a made-up words for my program.3
Filed under: softwareengineering - @ 17:56
Thẻ: comments, documentation
how to pluralize ‘special’ terms e.g. class names
Quite often I find myself referring in text to objects which have strict naming conventions e.g. Java objects, processes, services. I find myself in a dilemma over how to pluralize these names.
It seems wrong to pollute the meaningful name by adding an ‘s’ – or worse, a plural that modifies the rest of the name like SomethingUtility -> SomethingUtilities. What if someone does a text search looking for the name? Or cuts and pastes from my comment to search through a log file?
I have sometimes resorted to an ungrammatical apostrophe, but this can confuse plural with ownership.
Is there any better solution?
4
If the class name cannot be converted into proper English, while retaining it’s sense, then that’s usually indicative of bad class naming. That is, if you’re talking about a ShippingMethodRepository, then there’s rarely a reason not to write “shipping-method repository” and thus “shipping-method repositories”. This is easier for most people to read, because of the subtle visual clues in compound modifiers and such.
In the few cases where you feel a need to point to the class-name, if you give each situation some thought, you’ll probably find that you’re missing either the word “instance” or “class” in your sentence. I suggest putting it back in as a matter of course — it is easy to cause confusion by not being specific.
As a bonus, this will make it easier to pluralise. ie. “ShippingMethodRepository instance” becomes “ShippingMethodRepository instances”. (You’ll probably find that you never need to pluralise class in this context.)
0
In my
Documentations, I do it like we do it here on Stackexchange and use different fontStyles for specialTerms.For those terms where a different pluralization would be required according to English grammar, I just don’t do it. My excuse for this is that the names of my
Classs are not English words. They are a made-up words for my program.3
Filed under: softwareengineering - @ 17:56
Thẻ: comments, documentation
how to pluralize ‘special’ terms e.g. class names
Quite often I find myself referring in text to objects which have strict naming conventions e.g. Java objects, processes, services. I find myself in a dilemma over how to pluralize these names.
It seems wrong to pollute the meaningful name by adding an ‘s’ – or worse, a plural that modifies the rest of the name like SomethingUtility -> SomethingUtilities. What if someone does a text search looking for the name? Or cuts and pastes from my comment to search through a log file?
I have sometimes resorted to an ungrammatical apostrophe, but this can confuse plural with ownership.
Is there any better solution?
4
If the class name cannot be converted into proper English, while retaining it’s sense, then that’s usually indicative of bad class naming. That is, if you’re talking about a ShippingMethodRepository, then there’s rarely a reason not to write “shipping-method repository” and thus “shipping-method repositories”. This is easier for most people to read, because of the subtle visual clues in compound modifiers and such.
In the few cases where you feel a need to point to the class-name, if you give each situation some thought, you’ll probably find that you’re missing either the word “instance” or “class” in your sentence. I suggest putting it back in as a matter of course — it is easy to cause confusion by not being specific.
As a bonus, this will make it easier to pluralise. ie. “ShippingMethodRepository instance” becomes “ShippingMethodRepository instances”. (You’ll probably find that you never need to pluralise class in this context.)
0
In my
Documentations, I do it like we do it here on Stackexchange and use different fontStyles for specialTerms.For those terms where a different pluralization would be required according to English grammar, I just don’t do it. My excuse for this is that the names of my
Classs are not English words. They are a made-up words for my program.3
Filed under: softwareengineering - @ 17:56
Thẻ: comments, documentation
how to pluralize ‘special’ terms e.g. class names
Quite often I find myself referring in text to objects which have strict naming conventions e.g. Java objects, processes, services. I find myself in a dilemma over how to pluralize these names.
It seems wrong to pollute the meaningful name by adding an ‘s’ – or worse, a plural that modifies the rest of the name like SomethingUtility -> SomethingUtilities. What if someone does a text search looking for the name? Or cuts and pastes from my comment to search through a log file?
I have sometimes resorted to an ungrammatical apostrophe, but this can confuse plural with ownership.
Is there any better solution?
4
If the class name cannot be converted into proper English, while retaining it’s sense, then that’s usually indicative of bad class naming. That is, if you’re talking about a ShippingMethodRepository, then there’s rarely a reason not to write “shipping-method repository” and thus “shipping-method repositories”. This is easier for most people to read, because of the subtle visual clues in compound modifiers and such.
In the few cases where you feel a need to point to the class-name, if you give each situation some thought, you’ll probably find that you’re missing either the word “instance” or “class” in your sentence. I suggest putting it back in as a matter of course — it is easy to cause confusion by not being specific.
As a bonus, this will make it easier to pluralise. ie. “ShippingMethodRepository instance” becomes “ShippingMethodRepository instances”. (You’ll probably find that you never need to pluralise class in this context.)
0
In my
Documentations, I do it like we do it here on Stackexchange and use different fontStyles for specialTerms.For those terms where a different pluralization would be required according to English grammar, I just don’t do it. My excuse for this is that the names of my
Classs are not English words. They are a made-up words for my program.3
Filed under: softwareengineering - @ 17:56
Thẻ: comments, documentation
« Is there a way to enable word wrap to the tool tip that shows over the variable value in the Variables panel? ⇐ More Pages ⇒ how to pluralize ‘special’ terms e.g. class names »