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 */
Related
The Effective go has following advice on naming of getters:
Go doesn't provide automatic support for getters and setters. There's
nothing wrong with providing getters and setters yourself, and it's
often appropriate to do so, but it's neither idiomatic nor necessary
to put Get into the getter's name. If you have a field called owner
(lower case, unexported), the getter method should be called Owner
(upper case, exported), not GetOwner. The use of upper-case names for
export provides the hook to discriminate the field from the method. A
setter function, if needed, will likely be called SetOwner. Both names
read well in practice:
Source: https://golang.org/doc/effective_go.html#Getters
Now, this advice doesn't seem to consistent as the stdlib itself violates this multiple times.
As you can see in above screenshot, there are multiple methods which use GetX naming convention which is advised against in the effective go guide.
So the question is is the advice given in guide wrong or these methods are named wrongly & would be fixed in future versions?
These names are not consistent with Go naming by design. Rob Pike, one of the Go creators, says this about the names in the OS package:
There are inconsistencies but this is the key point. It should be Stdout not StdOut, because that name is coming from the underlying system. Similarly it's Fprintf not FPrintf or FPrintF because that is a very familiar name. These names are coming into Go, not being created there, and the initial cap is the admission fee.
The names will not be changed in a future version of Go.
[go-nuts] FunctionName caseinconsistencies
A lot of the all lowercase names were chosen before we had really
figured out what the naming conventions should be. The rule we
adopted, which might be worth revisiting later, was that entry points
in package os or syscall, which are named after equivalents in C, just
had a single capital at the beginning, to avoid needing to decide
where the internal capitalizations are in abbreviations like geteuid
or getwd or chdir. Names like Readdirnames, which are actual words,
might be worth revisiting at some point.
Russ
os: inconsistent casing in names #1187
Is there any sort of rule about the casing of functions used in the
"os" package? Looking through, it doesn't sound like it's very easy
to recall whether a given function should be called LikeThat or
Likethat.
For instance:
Mkdir
MkdirAll
TempDir
Getenv
ForkExec
Readlink
ReadAt
Readdir
It feels very ad-hoc, and hard to recall.
It's a known issue. It's unplanned.
The term "getters" refers to methods on structs that allow you to read values of (often unexported) fields on that struct. The functions you're pointing to are top-level functions which allow you to read values from the OS. That idiomatic rule is not relevant to this case.
Often in code snippets or examples, the prefix My is used for classes, methods, and variables.
We see this all the time, from Google's gcm example to numerous questions on stackoverflow. It can be found in documentation for PHP, Javascript, C#, and really just about every other language.
So, given it's extreme prevalence, why shouldn't I put MyClass with myMethod using myVar1 into production? Why is this bad practice, and what should I do instead?
Name are important
Everything else comes down to that one simple fact.
Having clear, meaningful variable names is an important factor in writing understandable and maintainable code. - Computational Fairy Tales
When you write a piece of code, you want anyone reading it (which includes you in three months!) to know what it does almost immediately. In order to remember, you would probably need to add a comment about it. However...
The proper use of comments is to compensate for our failure to express our self in code - Express Names in Code: Bad vs Clean
To help with this, your name should be both descriptive and concise. Generally, when the prefix My is added, it replaces a prefix that could be more informational. Instead of MyService, why not GcmListenerService?
What if I make it descriptive, but I just add My? Like MyGcmListenerService?
That breaks the consice part of the rule. What do you gain from adding My? Is the My adding value to the name? Even if you were attempting to take possession of the code (which would be better done and is feasible using vcs), My is meaningless. Who wrote My? Well, I did, obviously. It says it right there, "My".
If I really shouldn't use My, why is it in so many examples?
Really, it's just a placeholder.
It's like the metasyntactic variables "foo" and "bar" - it's usually used as a placeholder for a real name. - Opinions on using My as a class name prefix
Unfortunately, most experienced programmers just assume that people looking up examples will know this, and they will replace My with a good variable name when they actually use the code. However, for those new to programming, if you see it all over the place, instead of knowing it is a placeholder, you may think it is actually a standard, and best practice to use My.
Ok, then what do I use instead of My?
There are a lot of really good guides about naming variables and classes out there. You can start with wikipedia, but if you google around a bit you can find lots of articles about good vs bad names. At the heart of it all, though, is one rules: make names descriptive, and keep them concise.
If I read the name of a class, method, or variable and immediately know its purpose, it is a good name.
I am tidying up my ancient Cocoa code to use modern naming conventions. There has been lots of discussion on best practices, but I'm unsure of one thing.
I'm thinking about adding a prefix to category method names, to ensure uniqueness. It seem generally agreed that this is a good idea, though most people probably don't bother.
My question is: what about a NSDictionary category method like -copyDeep that does a deep copy? The method used to be named -deepCopy, but I reversed the words as the analyzer looks for a prefix of "copy". Therefore I presumably couldn't add a prefix. And having the "prefix" in the middle or end of the method name seems messy and inconsistent.
I'd also be interested in thoughts on the style of prefix -- I currently use DS (for Dejal Systems) for class prefixes. But I know that Apple now wants to reserve all two-character prefixes for themselves, so am thinking about using Dejal, e.g. my class DSManagedObject would be renamed as DejalManagedObject. And getting back to categories, their methods would be renamed to add a dejal prefix, e.g. from -substringFromString: to -dejalSubstringFromString:. But -dejalCopyDeep would confuse the analyzer, so maybe I'd have to be inconsistent for such methods, and use -copyDeepDejal or -copyDeep_dejal?
I will be re-releasing my categories and various classes as open source once I've cleaned them up, so following the latest conventions will be beneficial.
I emailed the Apple Application Frameworks Evangelist about this, and got a reply that recommended not prefixing category method names. Which conflicts with the advice in the aforelinked WWDC10 session, but I assume reflects Apple's current thinking.
He recommended just looking at the beta seed API diffs to spot conflicts, which is what I've always been doing.
I agree with Kevin Ballard, you should prefix your category method names, particularly if you are going to distribute them to others. But you do have a valid concern the analyzer will be confused by DScopy. The ARC compiler will similarly be confused if the definition/implementation of DScopy is done without ARC and is used by another class using ARC (or vice versa).
My preferred solution is to use "ownership transfer annotations", such as:
NS_RETURNS_NOT_RETAINED
NS_RETURNS_RETAINED
They would be used to override the compilers default behavior of reading method names and acting on them. You might declare DScopy like so: (This declaration must be in a header file that is imported by all the classes that use this method mentioned due to link)
-(DSManagedObject *)DScopy; NS_RETURNS_RETAINED;
Source for NS_RETURNS... WWDC 2011 Session 322 - Objective-C Advancements in Depth. The meat of this issue begins at about time 9:10.
A note about "But I know that Apple now wants to reserve all two-character prefixes for themselves". As a personal preference I like to use the _ character to separate the prefix from the name, it works well for me. You might try something like:
-(DSManagedObject *)ds_copy; NS_RETURNS_RETAINED;
This would give you three characters, and arguably make the method name more readable.
Edit In response to link posted in comment.
However as Justin's answer to your original question says that can be broken.
With regards to attributes; I did not suggest using __attribute__((objc_method_family(copy))) I suggested using NS_RETURNS_RETAINED, which translates to :__attribute__((ns_returns_retained)). While the first example there won't even compile (as he says) using - (NSString *)string __attribute__((objc_method_family(copy))); it compiles with - (NSString *)string; NS_RETURNS_RETAINED; just fine.
Obviously also if the NS_RETURNS_.. are "hidden" from the compiler in separate the .ms or indirected in some other way and the compiler can't see the directives then it won't work. Because of this I would suggest putting the declaration for any methods that may cause the analyzer/compiler confusion in your main .h file (the one that imports all the others) to limit the chances that there will be an issue.
it seems a trivial point, until you realize that you need consistency. Not being a native English speaker, I prefer to ask both for grammar and for style. Which one must be preferred among these method names, returning a list of URIs, each one associated to an object?
objectUriList()
objectsUriList()
objectUrisList()
objectsUrisList()
Also, do you consider good style to make explicit that the returned object is a list in the method name. Maybe something like objectUris() (or its correct form) would be fine and intuitive in any case.
I am not a native English speaker either. Correct form is either objectUriList or objectUris. Regardless of the number of objects and uris.
Car park = park of cars.
PC storage = storage of PCs.
oak forest
etc.
I would call is objectUriList(), it's just easier to say and essentially correct. It's clear that it returns a List which is a set of Uris, so you don't really need the plural there.
However, your final suggestion of objectUris() is also good, depending on how easy it is to see that it returns a List in your IDE.
objectUriList should be the correct answer.
(Unless the function runs on more than one object and then objectsUriList would be preferable).
I like to specify the returned object in the function name but because this is how I worked for my entire life (ever since crappier programming languages). Nowadays, I believe it's not necessary.
I would definitely go with the objectUris() alternative, omitting the "List" suffix. As you say, tidy and intuitive.
It's better to use ObjectUriList.
It is recommended in some circles not to include type names in member/parameter names, so you should drop the List part, but I find that "ObjectUriList" is much more explicit and meaningful than "ObjectUris", especially when you are likely to also have "ObjectUri" as a name nearby.
I think to differentiate between Array and List, It's good to append Array with 's' and List with 'list'.
I usually try to go with singular namespaces but sometimes and contextually plural namespaces as well. For e.g. if your return is always plural such as some keywords, I go with plural but if it can be singular often times, I stick to singular naming convention.
MSDN Guidelines states that class names should be Pascal cast with no special prefix, such as "C".
It is also states that names of class members, such as proprties and fields, should also be Pascal cast.
So, names ambiguity may arise in the case of a naming generic object.
for example, consider a class named "Polynom". An object instantiate from this class shuold be named "Polynom" also. Polynom = new Polynom.
Is it?
I think a more common guideline (that I have seen Microsoft themselves follow) is to name variables, including instances, camel-cased (lower first, upper all other words: variableName). So in your case, it would be polynom = new Polynom. Of course, I wouldn't actually name a variable polynom unless it had a very obvious use and only for a local space. Otherwise a variable name should describe what it does, not what type it is.
All that said, the most important part of any naming convention is not what casing goes where but that you are consistent with it. Find something that works for you and stick to it!
[Quick edit: re-reading your question again, I see that you're mainly concerned about Properties. In this case, yes, it is very common to Pascal case them, so Polynom would be resonable. But since this is a property that would be exposed to the user (otherwise why is it a property?) Please don't name it Polynom!!! Do something more descriptive, we have intellisense if we want to know the type.]
You may often see
PolyNom polyNom = new PolyNom();
Although most of the time this is not the most readable code. Is it just any old polyNom, or is it for a specific purpose. Steve McConnell sites in Code Complete that the optimal variable name length for debugging (reading code) is 10-16 characters, with 8-20 characters being about the same (pg. 262 second ed.) this gives you a lot of room to more accurately describe exactly what your variable is.