Related
I just dived into the world of using dispatch_queue a little bit more intensively and was wondering if there are some naming conventions that should be used just for GCD objects, so that the code of the classes is then more easily divided into GCD and other Code.
Or could it be that it is a bad idea to have separate naming conventions for GCD?
I'd suggest to simply stick to the usual Cocoa and CoreFoundation naming conventions. Extend them as needed.
Edit after comments:
First of all, you shouldn't start variables with an underscore as this is reserved for Apple. Instead, I recommend to postfix with underscore, like someVariable_ or prefix with something else (for example, a colleague of mine uses i_ for instance variables and g_ for globals).
Whether you want to add some kind of polish notation (like prefixing with q_ for queues) is entirely up to you, it's a matter of taste. I think it's more important that you can recognize what a variable is used for, like imageProcessingQueue_ instead of just queue_.
The problem is that this is entirely subjective and cannot be answered in an "this is the ultimate truth" way. Common sense and forethought are important and laziness (abbreviated names or very generic terms like simply queue_) should be avoided.
If I am naming a new class in an OOP language, which is a better convention:
XMLWriter
Most common
XMLwriter
Easier to distinguish
XmlWriter
No longer an acronym
XML_Writer
Removes the point of camel case
Pedantic yes, but I'm curious who uses what and why.
Java conventions seem lately to favor treating well-known acronyms like words, so: "XmlWriter"...
http://www.ibm.com/developerworks/library/ws-tip-namingconv.html
Java Naming Convention with Acronyms <-dupe question?
http://geosoft.no/development/javastyle.html
But nobody seems to be very consistent. Take JavaScript's XMLHttpRequest for example. What a trainwreck!
I'm pretty sure all the different naming convention people will want to string me up for saying this. But in my opinion the naming convention you should use should be the one that is easiest to read. Names are only used by humans, so therefore they should be whatever is easiest to read/understand. So for things like XMLWriter, I would probably put it as XmlWriter since that seems a little easier to read. For things that are very very common (i.e. XML) I think treating it as a word works best. If you have some acronym that is specific to your domain, then I might capitalize it so that people who don't use it all the time would understand that it's an acronym. Basically make it easier to understand the names real intention even if it makes it slightly harder to read. I think using common sense and best judgment is better than trying to stick to a absolute set of rules in naming. Although the naming should try it's best to follow a reasonable set of naming conventions.
I would say you should always prefer the most readable one (as zipper said) and atleast start the class name with capital letter as somewhere i read that its a Java standard convention and I also feel that starting with a capital letter always makes you sure that its a Java class.
I am wondering what is actually the preferred way of naming variables: some_variable or somevariable.
Looking at some libraries, I have seen both. What is more, some wide-spread style conventions like Google C++ Style Guide allow both.
What do you prefer and why? Is there a rule or good practice which tells when to use which? And does the same applies to argument names in functions/methods?
And is mixing those two conventions a good idea? If yes, when should the first naming conventions be used, and when the second one?
Use what's most readable and least confusing.
You should follow whatever naming convention makes sense to you.
For me, I always use camelCase for variables and PascalCase for public methods and properties.
The C++ standard libraries use both conventions for function and class names, though the _ convention is apparently gaining popularity (it's used in most recent additions, since the STL got standardized). Stick with your project guidelines, or make up your own, but apply them consistently.
My personal style is to use some_function for functions, somevar for variables, PascalCase for class names. I don't have a copy of The C++ Programming Language by Stroustrup around, but I believe this is his style as well.
I'm currently in University and they're pretty particular about following their standards.
They've told me this:
All classes must start with a capital
letter
Correct
public class MyClass {}
Incorrect
public class myClass {}
public class _myClass {}
All methods must start with a
lowercase letter
Correct
public void doSomething() {}
Incorrect
public void DoSomething() {}
public void _doSomething() {}
all variables must start with a
lowercase letter
Correct
string myString;
Incorrect
string MyString;
string _myString;
Yet in my last year of programming, I've been finding that people are using much different rules. It wouldn't matter if it were just a few people using the different rules, but almost everywhere I see these different practices being used.
So I just wanted to know what the reasoning behind the above standards is and why some of these other standards are being used: (are they wrong/old standards?)
Most methods I've seen start with a capital letter rather than a lowercase-- Pretty much any of Microsoft's methods I've been using from their imported namespaces. This is probably the most common one I've seen that I don't understand
A lot of people use _ for class variables.
I've seen capitals on variables ie. string MyString;
I know I've missed a few as well, if you can think of any that you could add in and give an explanation for that would be helpful. I know everyone develops their own coding styles, but many of these practices have reasons behind them and I would rather stick with what makes the most sense.
Thanks,
Matt
There is no valuable reason to choose one coding style rather than an other one.
The most important thing is to agree on a coding style with the people you are working on. And to help you to all agree on a coding style, your professor told you a coding style.
Most of the time, it is just a point of view. So, just follow your professor's coding style if you have to code with the university....
standards are arbitrary, like which side of the road to drive on; just do it like they tell you to do it ;-)
Most people are talking about naming convention style, but there are other things to consider when approaching naming conventions, such as what you actually name a routine.
Routine (methods, functions, and procedures) names should typically by in the form of a strong verb + object, regardless of how you format it. For example:
paginateResponse()
or
empty_input_buffer()
as (respectively) opposed to
dealWithResponse()
or
process_input_buffer()
Both "dealWith" and "process" are verbs, but they are ambiguous and cause any other programmers working with your code in the future to have to consult the actual routine definition to determine what it really does.
"Strong" verbs, on the other hand, as shown in the first two examples, are much more powerful in their descriptive power and really pin down what the routine is doing.
This makes your code easier to read as it is self-documenting and leads to higher levels of cohesion.
Also, as a personal point of style, I try to avoid at all costs using "my" in any name.
Standards are only standards if they are followed, and every company or institution has their own standards. It is one of the worst parts of programming. :D
Speaking specifically about the leading _. From my experience this is mostly used on variables that are declared private within a class. They are usually coupled with a method to retrieve them that has the same name without the leading _.
I am trying to follow the rules from Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries by Krzysztof Cwalina and Brad Abrams
Guidelines in this book are presented in four major forms: Do, Consider, Avoid, and Do not. These directives help focus attention on practices that should always be used, those that should generally be used, those that should rarely be used, and those that should never be used. Every guideline includes a discussion of its applicability, and most include a code example to help illuminate the dialogue.
Also, you can use FxCop to check your compliance with those rules.
Standards help with readability, and therefore improve maintainability. (because when you can read the code faster, easier and more accurately, you can debug and repair it, or enhance it, in less time and with less effort.)
They have no effect on reliability or availability, cause the computer doesn't care what the variables are named or how the souurce code is formatted.
If you code is well-organized and readable, you have achieved the objective, regardless of whether or not it conforms exactly to anyone elses "standard".
This says nothing, of course, about how to handle the environment where "standards" are high on someone's list of developer evaluation tools, or management metrics...
I see logic behind capitalisation of classes and variables; it means you can do things like
Banana banana; // Makes a new Banana called banana
I've been learning Qt recently, and they follow your conventions to the letter. I wouldn't ever follow Microsoft's naming conventions!
The standards I've seen echo what's in the Framework Design Guidelines. In the examples you've stated above, I don't see you distinguishing between visibility (public/private).
For example:
Public facing methods should be PascalCase: public void MyMethod() ...
Parameters to methods should be camelCase: public void MyMethod(string myParameter) ...
Fields which should always be private, should be camelCase. Some prefer the underscore prefix (i do) to distinguish it from method parameters.
The best bet on standards is to have your team agree upon conventions up front when the project kicks off, you'll find everything much more consistent.
Coding styles are based on personal preferences and to a large extent the features of the language that you're using.
My personal take is that it's more important to be consistent with a convention than picking the "right one". People can be dogmatic about they're preferred style and things can often delve into a religious war.
All classes must start with a capital letter - This goes hand-in-hand with variable naming and helps prevent confusion that would arise if you had both classes and variables named with the same rules. My preference is a capital letter because I'm used to it and it follows the guidelines for my preferred language (C#).
All methods must start with a lowercase letter - same goes, although I start my methods with an uppercase character (as per C# guidelines).
All variables must start with a lowercase letter - this, I believe, is dependent on you language's scoping features. Often people prefix variables (usually an underscore or a character like "g") to indicate a variable's scope ("g" might mean "global"). This can help prevent confusion where variables have the same names in different scopes. My C# driven preference: all variables have start with a lowercase letter and I use "this." to reference a global variable of the same name where scope is a problem (this usually only occurs in a class's constructor).
I can't let 3. go by without mentioning Hungarian notation (which is grossly misused and misunderstood). Joel has a great article that helped me understand these better.
In addition to the main point, that while any specific standard is essentially arbitrary but it's important to have some agreed upon standard, I'd also add that some standards are ubiquitous enough to have achieved the status of the "correct" way to do things.
For example, in java, class names in professional code are always in CamelCase. I'll qualify the always in saying that your code will compile if you break the standard, and you may occasionally find some open source projects that break the convention as well, but I believe that most people would take that as a sign that the author is not too familiar with the language. Most of your professors guidelines are fairly standard (for java, in any case). Being radically different in this case, apart from annoying your professor, will probably irritate total strangers ;)
It's interesting to me that some languages seem to have taken this standardization to heart, and enforce capitalization to have specific meaning (e.g. Haskell).
The rules you're citing are those used pretty universally in the Java world.
Are you doing Java code at university? If not, it may be that they were previously teaching Java, then switched to C# but kept the naming conventions.
The .NET standard of prefixing an interface name with an I seems to be becoming widespread and isn't just limited to .NET any more. I have come across a lot of Java code that uses this convention (so it wouldn't surprise me if Java used it before C# did). Also Flex uses it, and so on. The placing of an I at the start of the name smacks of Hungarian notation though and so I'm uncomfortable with using it.
So the question is, is there an alternative way of denoting that Something is an interface, rather than a class and is there any need to denote it like this anyway. Or is it a case its become a standard and so I should just accept it and stop trying to stir up "religious wars" by suggesting it be done differently?
From the Framework Design Guidelines book:
Interfaces representing roots of a hierarchy (e.g. IList) should also use nouns or noun phrases. Interfaces representing capabilities should use adjectives and adjective phrases (e.g. IComparable, IFormattable).
Also, from the annotations on interface naming:
KRZYSZTOF CWALINA: One of the few
prefixes used is “I” for interfaces
(as in ICollection), but that is for
historical reasons. In retrospect, I
think it would have been better to use
regular type names. In a majority of
the cases developers don’t care that
something is an interface and not an
abstract class, for example.
BRAD ABRAMS: On the other hand, the “I” prefix on interfaces is a clear
recognition of the influence of COM
(and Java) on the .NET Framework. COM
popularized, even institutionalized,
the notation that interfaces begin
with “I.” Although we discussed
diverging from this historic pattern
we decided to carry forward the
pattern as so many of our users were
already familiar with COM.
JEFFREY RICHTER: Personally, I like the
“I” prefix and I wish we had more
stuff like this. Little one-character
prefixes go a long way toward keeping
code terse and yet descriptive. As I
said earlier, I use prefixes for my
private type fields because I find
this very useful.
BRENT RECTOR Note:
this is really another application of
Hungarian notation (though one without
the disadvantages of the notation's
use in variable names).
It has very much become a widely adopted standard, and while it is a form of Hungarian, as Brent states, it doesn't suffer from the disadvantages of using Hungarian notation in variable names.
I would just accept it, to be honest. I know what you mean about being a bit like Hungarian notation (or at least abuse of the same) but I think it gives sufficient value to be worth doing in this case.
With dependency injection being in vogue, often I find I end up with an interface and a single production implementation. It's handy to make them easily distinguishable just with the I prefix.
One little data point: I work with both Java and C# a fair amount, and I regularly find myself having to check which types in Java are actually interfaces, particularly around the collection framework. .NET just makes this simple. Maybe it doesn't bother other people, but it bothers me.
+1 for IFoo from me.
As a .NET programmer (for the most part), I actually prefer the Java convention of dropping the I here, for a simple reason: Often, small redesigns require the change from an interface into an abstract base class or vice versa. If you have to change the name, this might require a lot of unnecessary refactoring.
On the other hand, usage for the client should be transparent so they shouldn't care for this type hint. Furthermore, the “able” suffix in `Thingable” should be enough of a hint. It works well enough in Java.
/EDIT: I'd like to point out that the above reasoning had prompted me to drop the I prefix for private projects. However, upon checking one of them against the FxCop rule set, I promptly reverted to the usage of I. Consistency wins here, even though a foolish consistency is the hobgoblin of little minds.
Its all about style and readability. Prefixing Interfaces with "I" is merely a naming convention and style guideline that has caught on. The compilers themselves couldn't care less.
My main assumption is that the most important thing is to maintain readability in domain part of the implementation. Therefore:
If you have one behaviour and one possible implementation, then just don't create an interface:
public class StackOverflowAnswerGenerator { }
If you have one behaviour and many possible implementations, then there is no problem and you can just drop the "I", and have:
public interface StackOverflowAnswerGenerator {}
public class StupidStackOverflowAnswerGenerator : StackOverflowAnswerGenerator {}
public class RandomStackOverflowAnswerGenerator : StackOverflowAnswerGenerator {}
public class GoogleSearchStackoverflowAnswerGenerator : StackOverflowAnswerGenerator {}
//...
The real problem comes when you have one behaviour and one possible implementation but you need an interface to describe its behaviour (for example for convenient testing, because of convention in your project, using some library/framework which enforces this, ...). Possible solutions, other from prefixing the interface are:
a) Prefix or suffix the implementation (as stated in some other answers in this topic)
b) Use a different namespace for interface:
namespace StackOverflowAnswerMachine.Interfaces
{
public interface StackOverflowAnswerGenerator {}
}
namespace StackOverflowAnswerMachine
{
public class StackOverflowAnswerGenerator : Interfaces.StackOverflowAnswerGenerator
{}
}
c) Use a different namespace for implementation:
namespace StackOverflowAnswerMachine
{
public interface StackOverflowAnswerGenerator {}
}
namespace StackOverflowAnswerMachine.Implementations
{
public class StackOverflowAnswerGenerator : StackOverflowAnswerMachine.StackOverflowAnswerGenerator
{}
}
Even though I think the last possibility is the cleanest, its one drawback is that even though using StackOverflowAnswerMachine; gives you access to all domain objects you must prefix all domain interfaces not to be confused with their implementations. That may feel like something not very convenient but in clean design usually a class doesn't use many other domain objects, and mostly you need to use the prefix only in field declaration and constructor parameter list. So, that is my current recommendation.
The client of domain functionality shouldn't need to know whether they're using an interface, an abstract class or a concrete class. If they need to know this, then there is some serious problem in such a project, because it has domain logic and infrastructural concerns mixed on the same abstraction layer. Therefore I recommend "a" or "c" solutions.
The coding standard for Symbian has interfaces (pure abstract C++ classes) denoted with an M rather than an I.
Otherwise, the only other way I have seen of denoting interfaces is through context.
For .NET, Microsoft's Framework Design Guidelines book absolutely recommends it, and yes, it is very much standard. I have never seen it done otherwise, and to create a new convention would only serve to confuse people.
I should add that I dislike Hungarian notation too, but this and the case of prefixing class variables with an underscore are good exceptions to me, because they make code so much more readable.
I've always thought this naming convention is a bit of a dinosaur. Nowadays IDEs are powerful enough to tell us that something is an interface. Adding that I makes the code harder to read so if you really want to have a naming convention that separates interfaces from classes I would append Impl to the name of the implementing class.
public class CustomerImpl implements Customer
You asked for an alternative, so here is one I have encountered:
Use no prefix on the interface class, but use a c or C prefix on the corresponding concrete classes. Most of your code will generally reference the interface, so why pollute it with the prefix and not the generally much less used concrete type.
This approach does introduce one inconsistency in that some concrete types will be prefixed (the ones with matching interfaces) and others will not. This may be useful since it reminds developers that an interface exists and its use should be preferred over the concrete type.
To be honest, I use the prefix on the interface, but I think it is more because I have become so accustomed and comfortable with to it.