Related
According to General Naming Conventions of .NET framework:
X DO NOT use abbreviations or contractions as part of identifier names.
For example, use GetWindow rather than GetWin.
X DO NOT use any acronyms that are not widely accepted, and even if they are, only when necessary.
I've once consider GetName can be used for my method, but I believe it's not so sematically meaningful.
In order not to deviate too far from the naming convention, I've tried to figure out widely accepted acronyms, but I just run out of ideas for the following method:
String GetExplicitInterfaceMemberImplementationName(MemberInfo info) {
return info.DeclaringType.Name+"."+info.Name;
}
For this case, it is, in fact, not really longer than the statement, but just the identical length; and Type.Delimiter should be used rather than ".". However, the naming problems so often bothers me.
So, what method name should I declare? And for the long-term solutions, what can I do?
For an additional question, is there an API out of the box does the same thing?
Edit 1:
Stop and think, such a good suggestion for me.
For the purpose of its statement, also for semantic and not breaking the naming conventions, I got an idea from [AddAttributeStoreCommand.TypeQualifiedName Property]; so I now declare it as:
public static String GetTypeQualifiedName(this MemberInfo info) {
return info.DeclaringType.Name+"."+info.Name;
}
Yet, a long-term solution hasn't come up ..
Edit 2:
I'm not sure whether it's a good practice to name like this ..
public static String GetTypeDotItsName(this MemberInfo info) {
return info.DeclaringType.Name+"."+info.Name;
}
Code Complete 2nd Edition has this to say about method name length:
Make names of routines as long as necessary
Research shows that the optimum average length for a variable name is 9 to 15 characters. Routines tend to be more complicated than variables, and good names for them tend to be longer. Michael Rees of the University of Southampton thinks that an average of 20 to 35 characters is a good nominal length (Rees 1982). An average length of 15 to 20 characters is probably more realistic, but clear names that happened to be longer would be fine.
Note the word average. If the method name is as clear as possible, and it's 50 characters, then whatever. It's fine.
However, the book does mention another thing a few paragraphs up:
If you have routines with side effects, you’ll have many long, silly names, The cure is not to use less-descriptive routine names; the cure is to program so that you cause things to happen directly rather than with side effects.
Of course, side effects aren't the issue here, but you can extend the idea. Ask yourself "Is this long, silly name popping up because I'm doing overly complicated stuff?" If you're sure that you need an ExplicitMemberInterfaceImplementationName, then fine, but it can at least be something to stop and think about.
1) Put in the information that is needed to make the purpose of the method clear. You can probably halve the length of your example name without any loss of understanding about what it fits.
2) guidelines are guidelines. Don't slavishly follow rules when they become counter productive. If using an abbreviation makes it easier to read and understand the code, use abbreviations. The main thing is to try to limit abbreviations to long names that are commonly used, and use intuitive and commonly used abbreviations for them, so that anyone reading your code can easily work out what they mean. For example, decl is a common abbreviation for declaration, and difficult to mistake for anything else.
3) sometimes you can avoid the need to abbreviate by using a synonym.
I think you could probably drop interface and member from your name without losing the meaning.
But perhaps the "explicit interface implementation name" is actually the "explicit name" - explicit has a well defined meaning, especially in the context if your class, and you can always add the fully watertight legal definition in your documentation comment. So: "GetExplicitName"
Should I place every class in separate file? Even those short helper classes that are used only in one place? Like this one:
public class IntToVisibilityConverter : GenericValueConverter<int, Visibility>
{
protected override Visibility Convert(int value)
{
return value == 0 ? Visibility.Collapsed : Visibility.Visible;
}
}
I do this and it is usually best practice to do so, but it is sometimes a matter of opinion.
That depends greatly of personal preference, but I like to do it.
In this case, I would have a folder inside my application called ValueConverters, and put all converters, including short ones, inside their own files.
I find it makes it easier to get an overview of what your project consist of from the Solution Explorer.
I'll rephrase the question for you: should I use StyleCop? (it includes this rule). The answer is yes. I use it and my code is much more readable (but I have to admit I disable all the rules that require the method documentation to be complete :-) )
I do think that when you program in a team, having a fixed and uniform code format is very important. And even when you program "solo". A cluttered code is more difficult to read and errors can hide better in the clutter :-)
It is usually the best practise to put every class in a seperate file. Taking into account your short helper classes; you could create a helper class which contain all your helper methods, to prevent having way too many classes. If your helper class gets too big, you can seperate your helper functions per category
It is good practice to do so.
You can easily find the class if you name the file after the class.
Resharper has a built in error for classes not matching the file name they are in...
Typically, IMO yes. Think about any new developers who must find where code lives. Yes, you can use go to definition, but that is not the be all, end all. However, I will say that sometimes if you have an interface that is small and only used for the class that it is within, then you can probably get away with it. However, even that can expand and later be required to be pulled out (and maybe those contracts should be in another namespace anyways).
So, ultimately, I would say the majority of the time, yes, but there are some caveats. As with anything, it is never black and white
I have for some time tried to anthropomorphise (meaning human readable) the names I give to interfaces, to me this is the same as give an interface a role based name – trying to capture the purpose of the interface in the name.
I was having a discussion with other developers who think this is a little strange and childish.
What do the folks of SO think?
Examples (C# syntax):
public interface IShowMessages
{
void Show(string message);
void Show(string title, string message);
}
public class TraceMessenger : IShowMessages
{
}
public interface IHaveMessageParameters
{
IList<string> Parameters { get; }
}
public class SomeClass : IHaveMessageParameters
{
}
IThinkItsATerribleIdea
Of course you should always choose identifiers which are human readable. As in: transport the meaning which they convey even to somebody who is not as familiar with the problem to be solved by the code as you are.
However, using long identifiers does not make your identifiers more 'readable'. To any reasonably experienced programmer, 'tmp' conveys as much information as 'temporaryVariable' does. Same goes for 'i' vs. 'dummyCounter' etc..
In your particular example, the interface names are actually quite annoying since somebody who's used to developing object oriented systems will read the inheritance as 'is a'. And 'SomeClass is a IHaveMessageParameters' sounds silly.
Try using IMessagePrinter and IMessageParameterProvider instead.
Yes, that sounds like a good idea.
What's the alternative?
Code should be human-readable. Any fool can write code a computer can understand. The difficult part is writing code a human can understand.
Humans have to maintain the code, so it's pretty darn important that it is as easy to maintain as possible - that includes that the code should be as readable as possible.
Interfaces describe behavior, and so I name them so as to to communicate the behavior they are mandating. This 'generally' means that the name is a verb, (or adverb) or some form of action-describing phrase. Combined with the "I" for interface, this looks like what you are doing...
ICanMove, IControllable, ICanPrint, ISendMesssages, etc...
using adverbs as in IControllable, IDisposable, IEnumerable, etc. communicates the same thought as a verb form and is terser, so I use this form as well...
Finally, more important (or at least equally important) than what you name the interface, is to keep the interfaces you design as small and logically contained as possible. You should strive to have each interface represent as small and logically connected a set of methods/properties as possible. When an interface has so much in it that there is no obvious name that would describe all the behavior it mandates, it's a sign that there is too much in it, and that it needs to be refactored into two or more smaller interfaces. So, maming interfaces in the way you are proposing helps to enforce this type of organizational design, which is a good thing.
There's nothing strange about using simple human-readable names. But using the I for interface to also stand for the first-person I as though it's talking about itself... is a little unusual, yes.
But the bottom line is, whatever works for you and is understood by you and your team is fine. You gotta go with what works.
In my opinion this approach just adds a greater burden on the developers to come up with such names since it intergrates the I as part of a sentence. I don't find IDisposable for example to be more difficult to read than ICanBeDisposed.
In the OP's examples, the anthropomorphic way compares well against alternatives - eg: IShowMessages vs. something like IMessageShower. But - this is not always the case. Interfaces I have used when programming game objects include: IOpenClosable and ILockable. Alternatives like ICanBeOpenedAndClosed and ICanBeLocked would be more verbose. Or you could simply do IAmOpenClosable and IAmLockable - but then you'd be adding the "Am" just for the anthropomorphic effect with no real information benefit. I am all for minimizing verbosity if the same amount of information is conveyed.
So long as the semantics of what is trying to be achieved aren't lost and terseness isn't irreparably compromised (IDoLotsOfThingsWhichIncludesTheFollowingColonSpace...). I wouldn't generally mind somebody other than myself doing it. Still, there are plenty of contexts in which terseness is paramount, in which this would be unacceptable.
Intentionally using the 'I for Interface' convention in the first person seems a bit silly to be honest. What starts out as a cute pun becomes impossible to follow consistently, and ends up clouding meaning later on. That said, your standalone example reads clearly enough and I wouldn't have a problem with it.
This question already has answers here:
Order of items in classes: Fields, Properties, Constructors, Methods
(16 answers)
Closed 9 years ago.
Is there a standard way of laying out a C# file? As in, Fields, then Properties, then Constructors, etc?
Here's what I normally do, but I'm wondering if there's a standard way?
Nested Classes or Enums
Fields
Properties
Events
Constructors
Public Methods
Private Methods
Do people group their fields together, or do they put them with the properties? Or do people not worry about an order? Visual Studio seems to make it so hard to do.
Edit: Moved other part about ReSharper here: Make Resharper respect your preference for code order.
I tend to use Microsoft StyleCop, which has a set order according to rule SA1201:
Cause An element within a C# code
file is out of order in relation to
the other elements in the code.
Rule Description A violation of this
rule occurs when the code elements
within a file do not follow a standard
ordering scheme.
To comply with this rule, elements at
the file root level or within a
namespace must be positioned in the
following order:
Extern Alias Directives
Using Directives
Namespaces
Delegates
Enums
Interfaces
Structs
Classes
Within a class, struct, or interface,
elements must be positioned in the
following order:
Fields
Constructors
Finalizers (Destructors)
Delegates
Events
Enums
Interfaces
Properties
Indexers
Methods
Structs
Classes
Complying with a standard ordering
scheme based on element type can
increase the readability and
maintainability of the file and
encourage code reuse.
When implementing an interface, it is
sometimes desirable to group all
members of the interface next to one
another. This will sometimes require
violating this rule, if the interface
contains elements of different types.
This problem can be solved through the
use of partial classes.
Add the partial attribute to the class, if the class is not already
partial.
Add a second partial class with the same name. It is possible to place
this in the same file, just below the
original class, or within a second
file.
Move the interface inheritance and all members of the interface
implementation to the second part of
the class.
I think there's no best way. There are two important things to consider when it comes to layout. The first most important thing is consistency. Pick an approach and make sure that the entire team agrees and applies the layout. Secondly, if your class gets big enough that you are searching for where those pesky properties live (or have to implement regions to make them easier to find), then your class is probably too large. Consider sniffing it, and refactoring based on what you smell.
To answer the reshaper question, check under Type Members Layout in Options (under the C# node). It's not simple, but it is possible to change the layout order.
I don't believe regions are necessarily a sign of bad code. But to determine that you will have to review what you have. As I've stated here this is how I regionize my code.
Enumerations
Declarations
Constructors
Methods
Event Handlers
Properties
But the main thing is keeping it consistent and purposeful.
I tend to clump private data and tend to clump related methods/properties in functional groups.
public class Whatever {
// private data here
int _someVal = kSomeConstant;
// constructor(s)
public Whatever() { }
#region FabulousTrick // sometimes regionize it
// fabulous trick code
private int SupportMethodOne() { }
private double SupportMethodTwo() { }
public void PerformFabulousTrick(Dog spot) {
int herrings = SupportMethodOne();
double pieces = SupportMethodTwo();
// etc
}
#endregion FabulousTrick
// etc
}
You can try Regionerate to help with this. I really like it and it's a Scott Hanselman pick.
As said, I don't think there is a best way as such. But some organisation does help you the programmer.
How often in a long project have you spent time going up and down one or more source files trying to find one of your functions.
So I make use of the #region a lot to in this sort of way -
region Events : All of the event references that this class uses (at least in this particular partial class).
region Controls : All functions that directly interact with controls on a form.
region MDI : set the mdi up
Then there will be some to do with functionality rather than interface,
region Regex searches
I sort of make it up as I go along, but using the same pattern I always use. I must say I have been told by some programmers picking up my work that it is easy to follow and others that its messy.
You can please half the people half the time and the other half a quarter of the time and the other quarter of the time you confuse everyone including yourself. I think Winston Chrchil said that.
Whatever makes your more productive. Some like private fields next to property accessors, some like fields together above the constructors. The biggest thing that can help is grouping "like," elements. I personally like bringing together private methods, private properties, etc.
Try some things out and again, whatever you feel makes you more productive and helps you keep your code maintained.
Each to their own, but I tend to follow the same order that the MSDN help follows.
I also don't like to nest classes or enums, instead create separate files for them, that also makes writing unit tests easier (since it's easy to find the associated test file when you need to add/fix/refactor a test).
IMHO the order isn't that important because VS makes it very easy to find all members (especially if you follow the one class/interface/enum per file approach), and Sandcastle will group them if you want to build docs, so I'd be more concerned about giving them meaningful names.
On top of keeping a consistent set of regions in your class files, I keep all components of a region in alphabetical order. I tend to have a bit of "visual memory" when it comes to reading code and it drives me crazy having to use the navigation dropdown to find code in a file because it's all over the place.
I use the following layout:
events
globals/class-wide fields
private/internal
properties
methods
public/protected
properties
methods
nested classes (although I try to avoid these whenever possible)
I also firmly believe in 1 code "thing" (class, interface, or enum) per file, with the file name the same as the "thing" name. Yes, it makes a larger project but it makes it infinately easier to find things.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
Just wondering why people like case sensitivity in a programming language? I'm not trying to start a flame war just curious thats all.
Personally I have never really liked it because I find my productivity goes down when ever I have tried a language that has case sensitivity, mind you I am slowly warming up/getting used to it now that I'm using C# and F# alot more then I used to.
So why do you like it?
Cheers
Consistency. Code is more difficult to read if "foo", "Foo", "fOO", and "fOo" are considered to be identical.
SOME PEOPLE WOULD WRITE EVERYTHING IN ALL CAPS, MAKING EVERYTHING LESS READABLE.
Case sensitivity makes it easy to use the "same name" in different ways, according to a capitalization convention, e.g.,
Foo foo = ... // "Foo" is a type, "foo" is a variable with that type
An advantage of VB.NET is that although it is not case-sensitive, the IDE automatically re-formats everything to the "official" case for an identifier you are using - so it's easy to be consistent, easy to read.
Disadvantage is that I hate VB-style syntax, and much prefer C-style operators, punctuation and syntax.
In C# I find I'm always hitting Ctrl-Space to save having to use the proper type.
Just because you can name things which only differ by case doesn't mean it's a good idea, because it can lead to misunderstandings if a lot of that leaks out to larger scopes, so I recommend steering clear of it at the application or subsystem-level, but allowing it only internally to a function or method or class.
Case sensitivity doesn't enforce coding styles or consistency. If you pascal case a constant, the compiler won't complain. It'll just force you to type it in using pascal case every time you use it. I personally find it irritating to have to try and distinguish between two items which only differ in case. It is easy to do in a short block of code, but very difficult to keep straight in a very large block of code. Also notice that the only way people can actually use case sensitivity without going nuts is if they all rigidly follow the same naming conventions. It is the naming convention which added the value, not the case sensitivity.
I maintain an internal compiler for my company, and am tempted to make it a hybrid - you can use whatever case you want for an identifier, and you have to refer to it with the same casing, but naming something else with the same name and different case will cause an error.
Dim abc = 1
Dim y = Abc - 1 ' error, case doesn't match "abc"
Dim ABC = False ' error, can't redeclare variable "abc"
It's currently case-insensitive, so I could probably fix the few existing errors and nobody would complain too much...
Many people who like case-sensitivity misunderstand what case-insensitivity means.
VB .NET is case-insensitive. That doesn't mean that you can declare a variable as abc, then later refer to it as ABC, Abc, and aBc. It means that if you type it as any of those others, the IDE will automatically change it to the correct form.
Case-insensitivity means you can type
dim a as string
and VS will automatically change it to the correctly-cased
Dim a As String
In practice, this means you almost never have to hit the Shift key, because you can type in all lowercase and let the IDE correct for you.
But C# is not so bad about this as it used to be. Intellisense in C# is much more aggressive than it was in VS 2002 and 2003, so that the keystroke count falls quite a bit.
There's a lot of answers here, but I'm surprised no one pointed out the obvious example that also makes fun of a stackoverflow competitor:
expertSexChange != expertsExchange
Case is very important when you use camel case variable names.
I believe it enforces consistency, which improves the readability of code, and lets your eye parse out the pieces better.
class Doohickey {
public void doSomethingWith(string things) {
print(things);
}
}
Using casing conventions makes that code appear very standarized to any programmer. You can pick out classes, types, methods easily. It would be much harder to do if anyone could capitalize it in any way:
Class DOOHICKEY {
Public Void dosomethingwith(string Things) {
Print(things);
}
}
Not to say that people would write ugly code, but much in the way capitalization and punctuation rules make writing easier to read, case sensitivity or casing standards make code easier to read.
I believe it is important that you understand the difference between what case sensitivity is and what readability is to properly answer this. While having different casing strategies is useful, you can have them within a language that isn't case sensitive.
For example foo can be used for a variable and FOO as a constant in both java and VB. There is the minor difference that VB will allow you to type fOo later on, but this is mostly a matter of readability and hopefully is fixed by some form of code completion.
What can be extremely useful is when you want to have instances of your objects. If you use a consistent naming convention it can become very easy to see where your objects come from.
For example:
FooBar fooBar = new FooBar();
When only one object of a type is needed, readability is significantly increased as it is immediately apparent what the object is. When multiple instances are needed, you will obviously have to choose new (hopefully meaningful names), but in small code sections it makes a lot of sense to use the Class name with a lowercase first character rather than a system like myFooBar, x, or some other arbitrary value that you'll forget what it does.
Of course all of this is a matter of context, however in this context I'd say 9 times out of 10 it pays off.
Case sensitivity is madness! What sort of insane coder would use variables named foo, foO, fOo, and fOO all in the same scope? You'll never convince me that there is a reason for case sensitivity!
It gives you more options.
Bell
bell
BEll
are all different.
Besides, it drives the newbies that were just hired nuts trying to find out why the totals aren't coming out right ;o)))
Because now you actually have to type everything in a consistent way. And then things suddenly begin to make sense.
If you have a decent editor - one that features IntelliSense or the same thing by another name - you shouldn't have any problems figuring out case-sensitive namees.
I usually spend some time with Delphi programming on vacation, and most of the other time I use only C++ and MASM. And one thing's odd: when I'm on Delphi, I don't like case sensitivity, but when I'm on C++ - I do. I like case sensitivity, becouse it makes similar words (functions, variables) look similar, and I like non-case sensitivity because it doesn't put excessive restrictions on syntaxis.
From
.NET Framework Developer's Guide
Capitalization Conventions, Case-Sensitivity:
The capitalization guidelines exist
solely to make identifiers easier to
read and recognize. Casing cannot be
used as a means of avoiding name
collisions between library elements.
Do not assume that all programming
languages are case-sensitive. They are
not. Names cannot differ by case
alone.
I think there is also an issue of psychology involved here. We are programmers, we distinguish minutely between things. a is not the same ASCII value as A, and I would feel odd when my compiler considers them the same. This is why, when I type
(list 'a 'b 'c)
in LISP (in the REPL), and it responds with
(A B C)
My mind immediately exclaims 'That's not what I said!'.
When things are not the same, they are different and must be considered so.
It's useful for distinguishing between types in code.
For example in Java:
If it begins with a capital letter, then its probably a class.
if its ALL_CAPS its probably a constant.
It gives more versatility.
Feels like a more professional way of coding. Shouldn't need the compiler to figure out what you meant.
I felt the same way as you a long time ago when i used VB3/4 a lot more. Now I work in mainly C#. But now I find the IDE's do a great job of finding the symbols, and giving good intellisense on the different cases. It also gives me more flexibility in my own code as I can have differnt meaning to items with different cases, which I do a lot now.
Also a good habit if your working in Linux where referencing file names is case sensitive. I had to port a Windows ColdFusion application to work in Linux and it was an utter nightmare. Also some databases have case sensitivity turned on, imagine the joy there.
It is good habit though regardless of platform and certainly leads to a more consistent development style.
IMHO it's entirely a question of habit. Whichever one you're used to will seem natural and right.
You can come up with plenty of justifications as to why it's good or bad, but none of them hold much water. Eg:
You get more possible identifiers, eg. foo vs Foo vs FOO.
But having identifiers that differ only in case is not a good idea
You can encode type-info into a name (eg. FooBar=typename, fooBar=function, foo_bar=variable, FOO_BAR=macro)
But you can do that anyway with Hungarian notation
Because it's how natural language works, too.
In progamming there's something to be said for case sensitivity, for instance having a public property Foo and a corresponding private/protected field foo. With IntelliSense it's not very hard not to make mistakes.
However in an OS, case sensitivity is just crazy. I really don't want to have a file Foo and foo and fOO in the same directory. This drives me cray everytime i'm doing *nix stuff.
For me case sensitivity is just a play on scopes like thisValue for an argument and ThisValue for a public property or function.
More than often you need to use the same variable name (as it represents the same thing) in different scopes and case sensitivity helps you doing this without resorting to prefixes.
Whew, at least we are no longer using Hungarian notation.
Case-insensitive languages don't easily generalize to non-ASCII character sets. Proper case conversion for a language other than English is not a straightforward task, and depends on system locale, among other things.
Case insensitivity is very difficult, unless you restrict the syntax to ascii (or only apply the case insensitivity to the ascii characters), and also you need to restrict the locale.
The rules for determining upper and lower case of characters is neither well defined, nor is it lossless.
Some characters can have more than one 'lowercase' form. Some people will disagree as to what the correct uppercase form should be.
(Some languages and environments allow for almost character to be used in names)
Consider In C# what is the difference between ToUpper() and ToUpperInvariant()?
After working many years with legacy VBScript ASP code, when we moved to .NET we chose C#, and one of the main reasons was case sensitivity. The old code was unreadable because people didn't follow any convention: code was an unreadable mess (well, poor VBScript IDEs helped on that).
In C# we can define naming conventions and everybody must follow them. If something is not correctly cased, you can rename it (with refactoring, but that's an IDE feature) and there won't be any problem because the class or variable will be named the same way all across the code.
Finally, I think it's much more readable if everything is correctly cased. Maybe it's faster to write without case sensitivity, but from a code reviewing and maintaining point, it's not the best thing because skipping through the code looking for something is easier. For example it's easier to find all the foo strings at a glance than looking for foo, Foo, FOO, FOo...