5 C# Naming Conventions I Wish Everyone Followed
Vložit
- čas přidán 24. 03. 2024
- In today's video we'll cover 5 C# naming conventions I think everyone should be following.
Naming can play a huge role in making your code more readable and maintainable. It can also reduce the time spent in debugging or figuring out what the heck is going on.
Connect with me on 'em socials:
Twitter: / amantinband
LinkedIn: / amantinband
GitHub: github.com/amantinband
Check out all my courses on DomeTrain:
dometrain.com/author/amichai-...
Support the channel and get the source code:
/ amantinband
Thanks for watching, don't forget to like & comment & subscribe! ❤️ 💻 - Věda a technologie
#5 one thing to note is using primary constructor here is not a complete replacement for private readonly DI via traditional constructor (captured or not), because the field that gets generated behind the scene misses the 'readonly' modifier (private field instead of private readonly field)
btw, the opposite of "id == x || id == y" should be "id != x && id != y" (you need to change the logical operator as well)
haha yeah I missed that. Someone already pointed it out. Good catch!
Good old De Morgan
With a big ! before everything.
!(a+b) = !a * !b => a+b = !(!a*!b)
Or, !(x&&y) ?
Rather than trying to do logic puzzles I prefer to just pull it out into a variable so you can read it almost like english.
var invalid = movieId == 68 || movieId == 421;
return !invalid;
01:26 - Boolean methods
03:01 - Positive names for boolean methods
04:51 - Testing methods names
08:33 - Private variables names
09:44 - Class parameters names
"Can" is also a valid prefix for boolean operations. For example; "CanMoveNext" for bounds checking or "CanExecute" as used by MS for MVVM commands etc.
Pretty much any prefix that indicates a state of 0/1.
Another common naming convention for methods that return a bool is the “Try” prefix, specifically for operations that swallow exceptions, returning a bool to indicate if the operation was successful instead of throwing.
Yeah I have a "Must Know C# Naming Conventions" video coming that will cover this as one of the conventions
@@amantinbandyes this one a favourite of mine, with the use of an out parameter if the method needs to return something following success
I disagree
"Is" in this case is valid, as it is only checking if something is true
"Try" is to attempt to get back a converted value. It's main intention is not to see if something is valid.
bool IsNumber(string x) would just let you if x is a number or not, and that's it
bool TryNumber(string x, out y) would try to convert the string to a number, and return a bool
And yes, TryNumber is not a good name
Love number 2! Sounds obvious now that I hear it but I was struggling with this the other day. These sort of things are really valuable when you're a beginner! Thank you 👏
I arrived at some of the same naming habits working on my own projects like using 'Is' for Booleans. I like the more subtle points about consistently using the positive versions of each term to reduce cognitive load though.
With number 5, you'll technically be making breaking changes every time you change your mind about whether or not you want a field to be captured.
What do you mean by breaking change? The only symbols you’ll need to update are private within the class
@amantinband
var someServive = new SomeService(_logger: logger);
Your decide you don't need to capture logger and this has to become
var someService = new SomeService(logger: logger);
That's a breaking change.
Probably fine in your projects for just your company/client. But any library maintainers need to take issues like this into account.
I’ve been following this convention in projects where objects are created via DI container or using a factory. Never manually. So unfortunately I haven’t given the named argument feature + this convention enough thought!
That’s 100% a good argument. I completely agree and think that this convention shouldn’t be used if the objects are manually initialized.
Thanks for commenting and making me second guess this 🙏🏼🫶🏼
In a similar vein, naming constructor parameters which are part of a classes public interface this way seems leaky - like a violation of encapsulation. Whether a field is captured or not is just a detail of compiler implementation & class implementation. I think naming a constructor parameter based on how it's used inside the class violates encapsulation.
Yeah, it looks like we are protecting class internals from modifications (i.e. we don't need to change private methods once a constructor argument becomes a read-only field) by exposing implementation details via the constructor signature. Usually we tend to do exact opposite.
For my personal projects I never use underscores for private fields. I code by the philosophy that every Logic, Service, Controller, Repository etc. are stateless and therefor do not have a private field such as a state or a name. So the only private fields are the Logic, Service, etc. and those have private fields are always injected and always their names always end with Logic, Service etc and that is telling me if a variable is a private Field or a parameter. So the underscore is redundant for my personal projects.
And personally, names with underscores are ugly and I never really got used to typing underscores. I always type it with only my right hand and it some kind of hurt a bit to type it. Perhaps because I have small hands? I don't know. But these are for me the reasons for not using underscores and I like it that way.
When I am coding in a team and the project we are working on, uses underscores, I do use them as well. I prioritize the the coding rules of the project above personal preferences. But I pray for the day that underscore convention will be removed.
I am using exactly the same convention :).
Cheers
What about,
a property named Enabled vs IsEnabled?
A sub convention we use for test methods is to always scaffold them with sections in this order:
// Arrange
// Act
// Assert
This makes it clear what each part of the test method is doing what in the test.
those get annoying really fast tbh., i found those more helpful when you educate people how to write a proper test, but not as a convention where you have to write it every time, as it elevates comments in a way.
Great video. Thanks for the excellent suggestions.
As the saying goes:
There are 2 hard problems in computer science: cache invalidation, naming things, and off-by-1 errors.
Naming convention is barrier to world peace when you have a team of very opinionated engineers. I do appreciate hearing your opinions and supporting reasons. I personally run into frustrations when conventions have no supporting reason behind them.
Consistency > convention choice. I think conventions should be deciding X in the beginning and sticking with it
Agree that consistency is better than convention, but I feel that a bad convention with no reason to exist, or one that differs too much from the idiomatic way, can do more harm than good (especially when new people see the code and get confused)
Thanks for sharing @Amichai. In the last point, you said that if it's not captured create your own private field with underscore convention.
if it's not being used, would it make sense to delete it altogether? Am I understanding the "captured" terminology incorrectly?
I don't stick to just Is / Has, my mentor generalized the rule such that a boolean property should:
0: Start with a verb that makes an explicit claim (Is Has Not Assert Ensure)
1: Indicates What is being claimed (Valid Invalid Acceptable Corrupt Null)
2: Includes the subject being referred to
IsValidNumber fulfills these, but does does EnsureValidId or NotInvalidNumber and all can be understood by the reader to make a solid claim of something about a subject.
3:00 For booleans I also sometimes use the "can" prefix. Like "canDoSomething" over "isAbleToDoSomething" when not possible via some kind "typeof interface".
Hello, thanks so much.
Can make a video about when we need to use addScoped, and addSingleton in the project API ..
I totally agree with your conventions. But when naming the tests, I use a different order.
_Sould_When.
I am trying to test the behavior, not the conditions.
This leads to the fact that in my class and also in the
CICD pipline log I get a "nice structure".
SUT_ShouldX_WhenA
SUT_ShouldX_WhenB
SUT_ShouldX_WhenC
IMHO it is more intuitive for colleagues to search by behavior and condition when analyzing than the other way around.
I've had a lot of discussions about naming the tests in our projects, and I'm constantly having to convince people.
I try to use the approach that we buckle up in the car, even though very few of us have been in a car accident. And if they have, most of them are happy to have buckled up.
Thats the second best version IMO. Just reads less naturally to me
I'm hesitant about using underscores in primary constructors as a naming convention. It introduces potential risks with change contracts. This situation might prompt a resurgence of the factory pattern down the line.
That’s a really good argument against this convention. If the objects in the solution aren’t initialized via a DI container or if they’ll be used by a 3rd party then this convention def shouldn’t be adopted
Hi Amichai, thanks for the video. I agree with most of what your conventions. I know this is somewhat of a standard, but personally I really don't like using an underscore for prefixing class fields. I just feels inconsistent and modern IDE's make it apparent if a variable is local or a class field.
you start putting underscores on my private fields and we're going to have a problem.
I already use most of these. Naming in our test-classes is still up for debate though I like the naming presented here. I'm still put off from using Primary constructors due to all the naming and the fact that readonly is not possible with the current implementation of Primary constructors.
I strongly disagree with the the underscore prefix. I do not see any value in the prefix. The only need for a prefix would be to avoid naming conflicts, but outside of the constructor there should be no reason for a naming conflict. If you do find a conflict odds are you just need to put more thought into names you are using. The only time there may be a naming conflict would be with dependency injection in the constructor. If this is the case, it doesn't make sense to add an prefix for this one exception, instead it is better to just use the built-in 'this' keyword.
As for primary constructors, their value is with records. Outside of that scenario they are just visual noise that create inconsistency in your code, and therefore should not generally be used.
what is tools is use when make arrow and rectangle 😇 I like them and what extensions is use in vscode thanks
I use Presentify. ZoomIt is a good (free) alternative if you're on windows
thanks you 🌹❤️@@amantinband
only came here because i wanted to know how you use the underscore, and e.g. in python, it always means private or temporary or unused variable, so the title ("underscore is captured") evoked my interest.
I have been using it in my C# as well, similarly to you, and also for temporary variables, that e.g. are only used once right after declaration and then not reused in the rest of the function, or assigned a value but not used at all as well, in the past.
I understand now, why you do it, but it also shows me kind of a downside, as now you have to flip your understanding for code generated primary values, where the ones that have no underscore are actually the ones that are temporary.
So I do not know what I think of that, given it kind of creates the same issue for me as the negative notation.
For primary constructors, I would look for a static code analyzer that forbids captures and forces the parameter to be used only for initializing private fields defined manually. Anything else is just too awkward for me.
That’s a good idea
Test naming: SUT_WhenA_ShouldX problem will arise as soon as you have multiple parameters, and require type names, that are subclasses of what a method returns or accepts:
FindProject_WhenQueryIsCatalogProjectQueryWithMinimumPagesAtLeast16AndFormatIsLandscape_ShouldReturnListOfCatalogProjectsThatMatchCriteria
where do the class and property/parameter names start and stop? compare to this:
FindProject_When_QueryIs_CatalogProjectQuery_With_MinimumPages_AtLeast16_And_Format_IsLandscape_ShouldReturn_ListOf_CatalogProjects_That_MatchCriteria
I'm afraid, I don't agree with your naming convention for methods that return bool. Sure, what you've suggested is nothing new as I've seen it being recommended and used before.
Personally, I prefer method names that read like, gramatically correct English. "if Is xxx" is just *never* correct in English. In fact "is" is not necessarily part of a grammatically correct sentence either.
Wrt, test method names. I agree about the importance of these names including that names of test methods are in fact more important than production code method names. But I prefer
Feature/method name_Scenario_Expectation
No need for prefixes such as Given, When, then etc.
My tests are primarily Acceptance/Functional test, so SUT doesn't really say much. the Feature being tested is much more important. Method names are generally feature names.
a question regarding this topic,
Do you prefer the Async suffix for async methods or not? I would like to know your reasoning
I think there is a video about it from Nick Chapsas
@@shayvt thanks. Yeah but I'm interested on Amichai's opinion 😊😉
Yep. Always Async. There is a nuget package I use to enforce it
@@amantinbandMay I ask which package is it?
We really need to get rid off the _ prefix.
It is a left over from the hungarian notation era but survived the HN massacre from some reason. 😁
Nowsdays your class should be simple and focused, if you have lost track whether a variable is private or not
your class is probably far too large and doing too much.
With the primary c'tor we can get rid of the _ prefix, just try it, you will not miss it.
I think the this. prefix was the main reason people kept the _ prefix,
but with primary c'tor it is really not needed anymore.
Putting the _ in parameter names is just ugly!
And also breaking when your clients are calling your class with named parameters and suddenly you decide to use an _ prefix ...
Whether an input variable ends up as private is an implementation detail the client doesn't need to known about.
Another debate is readonlyness of the input parameters of the primary ctor, or more precisely, the lost of it.
This doesn't stop me from using primary c'tors. It is a bad habit to alter input parameters anyway, so who is really doing this?
Nobody!
Just my 2 cents 😉
The contract break is a very good argument I didn’t take into account as my objects are created via the DI container or a custom factory (usually a static factory method).
Regarding ugliness, def subjective and cannot be argued.
HN is just redundant and long. Here, there a benefit of typing _ and getting all the private fields. It’s convenient when it’s a convention across the code base
@@amantinband
beauty is in the eye of the beholder 😅
sure _typing_ _ prefix is convenience, but I've also heard arguments about _reading_ _ prefix is convenience ...
For me both are unneeded nowadays. The IDE and PR tools are a lot better than decades ago.
Coming from a C++ background, the _ prefix always felt as something obsolete or system defined ...
In my own code I don't use them and don't miss them either.
In clients and teams code I adhere to the agreed coding standards, but I always challenge "why are we using this _ prefix"
Sometime times I win, sometimes I loose😉
Probably controversial, but i use style cop defaults. The main two rules I'm not fond of is using "this." for fields, and always wrapping with { } on simple if statements (particularly guard clauses). I know i can customise it. I know i don't like those two rules, but I've followed them for ages and to be honest I've got used to them. I'm personally not a fan of using an underscore for fields either, yes it's less typing, but it isn't as intuitive IMHO. So neither way seems great, and i can't think of anything better.
It should be `movieId != 68 && movieId != 421`. Logical 'and', not logical 'or'. Because any number is not 68 or not 421.
I don't like name `IsValidNumber`, because 68 and 421 are valid numbers as well. `isValidMovieId` is better in this case.
I think boolean method may begin with any correct question english word: `shouldX`, `wasX`, `needToBeX`. Or even something like `authorizationIsNeeded`. Not only `isX` or `hasX`.
Agree with other points.
Yep I missed that, also while editing 😆
Regarding the Boolean naming, I try to stay in the IsX and HasX territory but there are def times where a different prefix makes more sense as you suggested
What is the convention for static readonly field?
I use PascalCase
I've gone away from the _ for all private fields and just use camelCase for private & protected fields. I use the _ now to represent a backing field that should not be set directly and instead should use the PascalCase getter/setter that has extra logic and an auto property can't be used.
12:05
i dont like the last one, i keep accidentally using the wrong name, effectively capturing it twice. So i just call the parameter the same as the field.
Also i barely use the auto-capture feature because i want control over mutability.
I am on the fence for the naming of boolean properties. Enabled and Visible are kind of better than IsEnabled and IsVisible but is it worth to make the convention more complex for that?
The primary constructor parameter convention seems to me is objectively bad.
1. You are breaking the convention for parameter names (although you could argue that ship has sailed with positional records)
2. It is highly likely that at some point someone will change a captured parameter to not captured or capture a previously non-captured and forget to update the name.
3. You are leaking implementation details in public API. You might decide to change how the argument is used (the capturing) and then you change the name and break the clients using named arguments
Very good arguments on the primary constructor. Strongest case is breaking the contract.
This convention needs some more thought and def shouldn’t be used in projects where objects aren’t initialized via a DI container.
Regarding IsEnabled IsVisible, yes, I would prefer the Is versions. This is a convention I learned to appreciate when working in large team and large projects.
That said, none of these tips should become religious rules. Especially this one. If it’s a convention - great. Otherwise - also great 😁
@@amantinband DI doesn't solve the issue because what are you going to do, have one convention for DI initialized objects and another for the rest?
Why do const and static private fields aren't supposed to start with '_' as other private fields? Especially if most of them are readonly... I'd apply this rule even for protected fields to get a quick access to them by typing "_", and to avoid to have both "_logger" and "Logger" 😊
Names of boolean methods can break English, i.e. "Exists" is much more preferable than "IsExist". Newbies (like me 5 years ago) always do the second variant 😢
Let's see the whole list of possible namings!) maybe it's an idea for the next vid?..
Anyway you do a great job, thanks
I use PascalCase for const/static fields. I don’t have a good argument for why what you suggested isn’t better though.
There are def times where a different prefix/no prefix makes more sense than blindly prefixing an Is or Has
How about private properties, private static properties etc.
Another thing that always bothers me is when we override method arguments:
"myArg = myArg.Trim(), myArg = myArg.Replace(...)" makes it very hard to understand what the original method input was.
Private property - shouldn’t exist. Private static - PascalCase
All movies are valid...
I totally agree on positive checking booleans but I completely disagree on inverting the name of a method to avoid negation (refactoring to IsInvalidSomething in the video). The method should be positive otherwise you are just pushing the problem one step farther and it’s way worse to have a negative method then a negative check… at the end of the day I check negatively or positively on a bool depending on the needs, but now if I need the negative of the invalid is a double negation my brain struggles more to understand
You misunderstood me (or maybe I wasn’t clear enough). I inverted it as an example for what *I wouldn’t do*
Saying "the underscore provides extra information about the variable in question" is a miniature version of Hungarian notation, a style recommended by Microsoft in the mid-90's which was eventually deprecated as being more a hindrance than a help. By the time C# came out, they had discarded that way of thinking entirely, but some people still brought in the _ from C/C++, where it's very commonly used.
Your example in the video also misses some points.
public class MyClass1(int myPrivate){
private readonly int myPrivate = myPrivate;
public bool DoSomething(int value){
myPrivate = 0;
return myPrivate == value;
}
}
This will fail with a compiler error because referring to myPrivate gets you the readonly field, not the class parameter. The class parameter is masked by the readonly field having the same name, so cannot be referenced elsewhere in the class.
public class MyClass2(int myPrivate){
private readonly int _myPrivate = myPrivate;
public bool DoSomething(int value){
myPrivate = 0;
return myPrivate == value;
}
}
This will _not_ generate a compiler error, because myPrivate is still in scope throughout the entire class, despite being assigned to the _myPrivate field. Maybe you have it in your head that you need to use the _ version, but the next maintainer just sees the parameters on the class itself, so assumes that's the version to use. This leads to bugs from possibly invalid usage or assignments.
This was not an issue with standard constructors, but becomes one with class constructors. This probably causes the most friction for people who use the _ for private fields because changing from a standard constructor to a class constructor introduces potential problems that didn't exist before. This is not an issue for people who did not use _ on their fields because assigning the readonly fields keeps everything as safe as it was before. Of course you still need that boilerplate if you want the fields to be readonly, which reduces the value of the syntactic sugar being supplied a bit.
public class MyClass3(int _myPrivate){
private readonly int _myPrivate = _myPrivate;
public bool DoSomething(int value){
_myPrivate = 0;
return _myPrivate == value;
}
}
This will fail with a compiler error just like MyClass1. However it introduces noise to the callers of the function, since the parameter name now has that underscore in there, which deviates from expected convention.
public class MyClass4(int myPrivate){
public bool DoSomething(int value){
myPrivate = 0;
return myPrivate == value;
}
}
This will _not_ generate a compiler error. The parameter is read-write, and there's no attempt to make it readonly. It might be deliberate here, but could cause issues with a lot of dependency injections, such as the ILogger.
And as someone else already mentioned, adding or removing the underscore on the class constructor has the potential to be a breaking change.
More importantly, this exposes internal implementation details, which callers should not need to be aware of.
Good arguments and a great demonstration of why sticking with a convention, whatever it is, is better than mixing approaches
C# naming conventions are funny, fuzzy and messy.
תעשה לנו סרטון איך מגדירים editorconfig טוב בצורה של מיקרוסופט, ואולי בכללי איך עושים אצלכם FORMATTING
אין משהו מרגש מידי באיך שמגדירים editorconfig במיקרוסופט, לפחות לא מהניסיון שלי
If y write c#, write like this.
If y write javascript, write like this
If y write python, write like this.
So, languages nowadays have accents!
I write like I DO.
I totally agree with the "it's a preference" part, and in most part i agree with the presented content, but i strongly disagree with the _ before the private members.
1. you are forced to remember how you will use it in the class, if you then change the usage (maybe capture, you have to rename things around)
2. are ugly for a consumer of the class (IDE may suggest name with _ in the constructor)
3. you cannot "brainless" do trick like
public class MyClass(int myPrivate){
private readonly int myPrivate = myPrivate;
public bool DoSomething(int value){
return myPrivate == value;
}
}
note that this does multiple things, prevents the misusage of myPrivate that now it is always a readonly even if used in method because the readonly definition one took precedence and hides the one in the primary constructor in any of the methods of the class, plus the one in the constructor is not captured at all (memory saving for the machine, less things to remember also for my brain). also as side effect if i type wrong = it really give me an error
also the code is more pleasant to read (but it is my opinion, you may disagree)
Modern IDEs provide more than enough feature to understand what is what.
Typing _ as any other prefix notation is an overhead that can be used for more useful things, and to me it is more prone to generate errors than the problem it saves.
Last, but is a my old battle, the C# documentation on "MSDN" don't use it. The original C# default naming convention from Microsoft (early 2000) explicitly discourage the usage of _ but maybe you are too young to remember, anyway it is out of discussion for legacy code, but still i won't use it neither for new one, it looks so low level to read, C# should be an high level language and names should be very human friendly ( I don't think people usually prefix the name of their cat with symbols), I'm sorry but i can't see where _ helps, maybe if one writes code with notepad...
In the end, it's personal taste, but there are good reason to not do it in my opinion, maybe different context shifts the weight of what to do and what not based on the circumstances, but i struggle to see where this can be beneficial.
I honestly don't think it makes too much of a difference. I think consistency is more important on this one then which one to actually use.
Regarding your example, the following is less ambiguous IMO:
public class MyClass(int myPrivate){
private readonly int _myPrivate = myPrivate;
public bool DoSomething(int value){
return _myPrivate == value;
}
}
In any case, this is def a matter of taste. I don't think there is a clear right or wrong here. People's "taste" are likely more a matter of initial exposure than actual reasoning
I also totally agree with the part about "it's a preference," and regarding your points:
1) Yes, you're kind of forced to remember, but that's where the _ helps. Also, later you talk about IDE features, and renaming shouldn't be a problem with our current tools.
2) If it's a private member, there's no consumer of the class that would be accessing that field.
3) I agree with Amichai's comment.
And about the IDE features, it's true, but in this scenario, I prefer to keep the _ because most of the time I review PRs in the browser, so I don't really have my IDE features there.
I disagree with the first convention. It could very well be named "NumberIsValid()". And there are other verbs and tenses, for example "UserRequiresElevation()" or "PreviousValueWasDifferent()". I prefer to follow what looks more natural in spoken language, especially when the line it will be read in usually starts with "if".
That was my original instinct when I started coding, and what I went with for quite a while.
I think coding in a way where it reads like English is a very good approach, but doesn’t necessarily scale well when there are many devs working on the same project
please speak slowly :)
0.75x doesn't help? If not I'll take it down a notch
like this comment for "speak slower"
and this for "keep the speed as is"
SUT_ShouldX_WhenY - that's what I use.