Related
I often come across the pattern that I have a main class and several smaller helper classes or structs.
I'd like to keep the names of thoses structs as clean as possible. So when I have a class that's called CarFinder that heavily makes use of some special Key object that is only (or mainly) used internally, I'd like to call that object Key instead of CarFinderKey.
Everything to remove all the extra fuzz that distracts me from when I try to understand the class while reading it.
Of course I don't want to pollute the rest of the code with a small helper class that is called Key - it most likely will clash and confuse.
In a perfect world I would have liked to have a keyword like internal to this namespace, but as that does not exist that leaves me the following options that I can think of:
Use internal and put the class in a different project.
Advantage: Perfect encapsulation.
Disadvantage: A lot of organisational overhead and unnecessary complicated dependencies.
Note: I'm not talking about really large self contained systems that undoubtedly deserve their own assembly.
Put it in a different child namespace, like CarFinding.Internal
Advantage: Easy to implement.
Disadvantage: Still can pollute when the namespace is accidently imported.
Put the helper class as a child class within CarFinder.
Advantage Doesn't pollute internally and can even be promoted as a public helper struct that is exposed to the outer world with CarFinder.Key
Disadvantage Have to put the helper class within the same file, or encapsulate it in an external file with public partial class around it. The first one makes a file unneccesary long, the second just feels really ugly.
Anyway call it CarFinderKey
Advantage Easy to implement.
Disadvantage Adds in my opinion too much fuzz to CarFinder. Still unncessary pollutes the naming, just with a name that is not likely to clash.
What is the recommended guideline?
Personally, I don't mind the extra "fuzz" caused by CarFinderKey, and here is why: Once worked on a very large project where we tried to use namespaces to disambiguate names.
So as you expand your system, you can very easily end up with 10 tabs open in your code editor, all named "Key.cs". That was seriously not fun.
It's opinion based. Anyway, I would:
try to make it a private nested class of CarFinder, which usually fails because the Key needs to be passed over to CarManager, you know what I mean. Public nested classes are discouraged.
I would put it into a sub-namespace called Core, a common name for internal stuff. For me, Core is "namespace internal" by naming convention.
The larger the project, the longer names you need. CarFinderKey is still a valid option.
I would never create additional assemblies just for this. It just doesn't feel right.
I had the same dilemma many times, and personally use (3) and a variation of (4).
(3): I have no problem with neither putting the nested class/struct within the same file (if it is small and really tied with the parent class), nor using a separate file within partial ParentClass declaration - the only drawback is that it gets one more level of indentation, but I can live with that. I also have no problem with violating FxCop rules or other recommendations - after all, they are just recommendations, not mandatory. But many people do have problems with all or some of these, so let move on.
(4): You already described the cons. What I'm going to share is how I do overcome them. Again, it's personal and one might or might not like it, but here it is.
First, let say we use a separate file for the key class and name the class CarFinderKey.
Then, inside the code file for the CarFinder class, we put the following line at the end of (or anywhere inside) the using section:
using Key = CarFinderKey;
This way, only inside the CarFinder class code file, anywhere CarFinderKey is needed, we can just refer to it simply as Key, what was the goal. At the same time we keep all the advantages and no clashes. Intellisence works w/o any problem. In VS2015, the lightbulb would even suggest to "simplify the name" for you anywhere it finds CarFinderKey inside that file.
Your decision should depend on your design. Is your Key class really a key only for CarFinders, or could it also be used to find motorcycles or houses or whatever.
One of the first rules the famous Gang of Four stipulated was "Design for change". If you really think that in the very near future your key could also be used to find houses or motorcycle, then it would not be a good idea to make your key class thus private that other could not use it.
Since you are speaking about private helper classes, I assume your key is only useful for CarFinders.
If that is the case and your design dictates that the Key is only useful for CarFinders, or maybe even: if it is designed such that it even isn't useful outside CarFinders the Key class ought to be part of the CarFinders class. Compare this to a simple integer that you would use in the CarFinders class, you would declare it private inside the CarFinders class wouldn't you?
Leaves you with the problem of one big file or a partial definition. From design point of view there is no difference. For the compiler there is also no difference. The only difference is for humans who have to read it. If you think that users of your class seldom have to read the definition of your key class, then it is better to define it in a separate file. However, if you regularly need to read the key class while reading the CarFinder class you should make access to the key class as easy as possible. If your development environment is fairly file oriented instead of class oriented, then I think that in that case the disadvantage of a large file is less than the disadvantage of having to switch between files.
I would put the class and their "helpers" in their own namespace MyNamespace.CarFinding,
so that you have :
MyNamespace.CarFinding.CarFinder
MyNamespace.CarFinding.Key
and I will just put this namespace in a sub-folder of the project.
This will not block the internal helper class to be used elsewhere in the project, but from the parent namespace you could reference your helper as CarFinding.Key
Is there a concept in C# of class definition and implementation similar to what you find in C++?
I prefer to keep my class definitions simple by removing most, if no every, implementations details (it depends on several factors as you may know, but generally I move towards leaving most member implementation details outside the class definition). This has the benefit of giving me a bird's eye view of the class and its functionality.
However in C# it seems I'm forced to define my member functions at the point of declaration. Can this be avoided, or circumvent some way?
During my apprenticeship of C#, this is one aspect that is bothering me. Classes, especially complex ones, become increasingly harder to read.
This is really a case of needing to step back and see the bigger picture. Visual studio has many, many tools to help you write and manipulate your code, from outlining, #regions, class view, class diagrams, the Code Definition Window and many more.
C# isn't C++, if you try to make it so then you'll trip over yourself and no-one else will be able to read your code.
A day spent learning to use the Visual Studio tools will repay the investment many times over in terms of productivity and you'll soon wonder how you ever lived with that C++ way of doing things.
Update in response to comments
I have long since stopped regarding my code as simple text files. I regard code as an organic thing and I find that allowing myself to rely on a feature-rich IDE lets me move up and down levels of abstraction more easily and enhances my productivity no end. I suppose that could be a personal trait and perhaps it is not for everyone; I have a very 'visual' mind and I work best when I can see things in pictures.
That said, a clever IDE is not an excuse for poor style. There are best practices for writing "clean code" that don't require an smart IDE. One of the principles of clean code is to keep the definition of something near its use and I think that could be extended to cover declaration and definition. Personally, I think that separating the declaration and definition makes the code less clear. If you are finding that you get monster classes that are hard to understand, then that might be a sign that you're violating the Single Responsibility Principle.
The reason for separate definition and declaration in c/C++ is because C++ uses a single pass compiler, where forward references cannot be resolved later, unlike C# and its two-pass compiler which can happily find references regardless of the order of declaration. This difference stems from the different design philosphies of the compilers: C/C++ considers each source file to be a unit of compilation, whereas in C# the entire project is considered to be the unit of compilation. I suppose when you are used to working in the C/C++ way then separating the declaration and definition can appear to be a desirable element of style, but I personally believe that keeping declaration and use (or in this case declaration and definition) enhances, rather then reduces, readability. I used to be a C programmer myself until I started using C# in 2001. I always loved C and thought it's way of doing things was the 'bees knees'. These days when I read C/C++ code I think it looks absolutely horrendous and I can't believe we used to put up with working that way. It's all a matter of what you are used to, I suppose.
If you're using Visual Studio, you can take advantage of the Class View. You can also use the expand/collapse features of the source code editor.
In the improbable case that your tools don't help, you can always write a quick utility that will summarize the class for you.
If the class has been compiled, you can use Reflector to view the class, too.
No, there is no concept of implementation and header files in C# like you find in C/C++. The closest you can come to this is to use an interface, but the interface can only define the public members of your class. You would then end up with a 1-to-1 mapping of classes and interfaces, which really isn't the intent for how interfaces are to be used.
You could get a similar result by defining an interface for each of your classes which they then implement.
It sounds like you're referring to interfaces. In c#, you can define all of your member functions in an interface, and then implement them in another class.
In C# you could fake it with partial classes and partial members to a point, however, forward declarations and prototypes go the way of the dodo bird with your newer languages. Class View, Class Diagrams, Intellisense, et al, all help to remove the potential need for those "features".
Define an interface.
Then it's nice to be able to automatically implement the interface using a nice code assist tool.
If you find that a class is hard to read or difficult to understand, that's often a sign that the class is trying to do too much. Instead of trying to duplicate C++'s separation of declarations and definitions, consider refactoring the troublesome class into several classes so that each class has less responsibility.
Whenever it's possible or desirable, I'll go with the previous responses and define an interface. but it's not always appropriate.
alternatively, you can work around this "problem" by using some static code inspection tools. Resharper's "File Structure" window will give you exactly what you want. you can also use the built in "Class View" from visual studio. but I prefer the former.
The prototyping that I guess you are referring to does not really exist in C#. Defining interfaces as others have suggested will give you a point where you have declarations of your methods collected, but it's not the same thing as prototypes, and I am not so sure that it will help you in making your implementation classes easier to read.
C# is not C++, and should probably not be treated as C++.
Not sure what you mean by your classes continue to grow and become hard to read. Do you mean you want a header file like view of a class's members? If so, like John suggested, can't you just collapse the implementation so you don't have to see it?
If you don't want every class to implement a certain thing, then interfaces are probably the way to go (like others are saying).
But as a side thought, if your classes themselves get more and more complex as a your write the program, perhaps it's more of a design issue than a language problem? I think a class should have one responsibility and not take on more and more responsibilities as the program grows, rather the number of classes and how old classes are used should grow and get more complex as you continue to develop your software?
There are two remedies for this to make it more C++-ish:
Create an interface file that declares all method signatures and properties
Implement that interface in a class across multiple files by using the partial modifier on the class definitions
Edits:
// File: ICppLikeInterface.cs
public interface ICppLikeInterface
{
...
}
// File: CppLikeImplementation1.cs
public partial class CppLikeImplementation : ICppLikeInterface
{
...
}
// File: CppLikeImplementation2.cs
public partial class CppLikeImplementation : ICppLikeInterface
{
...
}
The C++ way of separating interface into a header file is mostly (I think) due to an early design decision when C was created to allow fast, incremental compilations during the "old days", as the compiler throws away any meta data, contrary to Smalltalk. This is not a matter with C# (nor Java) where tens of thousands of lines compiles within seconds on recent hardware (C++ still doesn't)
I know there exists already a post, describing nearly the same, but I think mine is a bit different.
What I would like to know is how you organize your extension methods in terms of assigning the namespace. Currently - for the extension methods in our framework - I use the following namespace pattern
MyCompany.Web.Utils
and inside I have the extension method classes. This is fine for me with the disadvantage that the extenders are not immediately visible to our software developers. Consider the case where I have a StringExtender class which provides a quite handy extension method "In" that extends the String object. Having the extension method withing the above mentioned namespace, our programmers won't see the extension method unless they explicitly include its namespace. Instead, if I would put the extension method in the System namespace, everyone would immediately see it, but I've read that this is bad practice.
So my question is how you do promote your extension methods s.t. they are used by your developers.
We put them all in their own namespace Company.Common.Extensions. That way, if you have any of our extension methods, you have them all. Plus, at least at my shop, we don't have to worry about our developers not knowing about extension methods. I have the opposite worry, extension method overload! :)
The problem here is not the naming of the namespace, it's the lack of documentation and education of your developers.
Put them in whatever namespace makes sense, write a wiki article documenting all your extension methods, then send an email to your developers with a link to the wiki article.
This is not a namespace problem it is a communication problem.
If these methods are useful you need to communicate this to the developers and, conversely, act on the feedback from them (with appropriate levels of judgement).
Placing anything into the System namespace is a recipe for disaster and confusion later. The only times you ever want to do this is to 'back port' functionality into older frameworks and then you probably shouldn't do it yourself but should use something like LinqBridge to do it.
Be wary of the desire to throw all extensions into one namespace unless they really are widely useful together. Some developers may find the wood lost for the trees if they are bombarded with everything and the kitchen sink via intellisense.
Keeping the namespace the company name is sensible in general to avoid confusion.
#Juri- If you think about it this is the same problem as developers knowing that class X exists in the .NET framework. Communication is key that all team members use the right classes, be they extension methods or some other helper.
As JP has stated, I often see extension methods in some kind of subfolder called Extensions. Hopefully when you state you use my.company.web.utils the namespace is actually Pascal cased?
Even if you put them in a good place there is no 100% guarantee that other developers will use them.
Presuming you use Visual Studio, one way would be to create a custom Class template (or modify the default one) so that whenever a developer creates a new class file it automatically has a using statement with your namespace(s). See Customize Visual Studio 2005 Templates for Coding Productivity.
Yes,i think put the Extension methods in own company namespce is best practices. put it in System namespace is a lazy operation
I'm dumb, lazy and minimalistic, so I put them at the same namespace as the type they extend. In this way there is no need for extra using statements, documentation or emailing about them (Winston).
I like the way ReSharper solves this problem.
ReSharper discovers any available extension methods, even without the corresponding usings. In case the using is not present, Intellisense also shows the namespace where the extension resides, making clear where the extension comes from and indicating that selecting it will add the using. (Example below.)
Naturally, only namespaces reachable by the current project, i.e. directly or indirectly referenced, are included.
Here is an example of what Intellisense might show if there are two extension methods. The first one comes from a namespace that we have already included. The second comes from a namespace that we have not (yet) included.
AddMvc
AddEntityFrameworkSqlServer (Microsoft.Extensions.DependencyInjection)
We put everything into the same Namespace and Class, however we use partial classes to keep them organized.
For example:
ExtensionMethods-String.cs
ExtensionMethods-DataObject.cs
ExtensionMethods-Debug.cs
...etc all have partial classes...
You can achieve what you want by putting extension methods in the global namespace. That's what I do and they're then available without needing any using statements.
I have been reading that creating dependencies by using static classes/singletons in code, is bad form, and creates problems ie. tight coupling, and unit testing.
I have a situation where I have a group of url parsing methods that have no state associated with them, and perform operations using only the input arguments of the method. I am sure you are familiar with this kind of method.
In the past I would have proceeded to create a class and add these methods and call them directly from my code eg.
UrlParser.ParseUrl(url);
But wait a minute, that is introducing a dependency to another class. I am unsure whether these 'utility' classes are bad, as they are stateless and this minimises some of the problems with said static classes, and singletons. Could someone clarify this?
Should I be moving the methods to the calling class, that is if only the calling class will be using the method. THis may violate the 'Single Responsibilty Principle'.
From a theoretical design standpoint, I feel that Utility classes are something to be avoided when possible. They basically are no different than static classes (although slightly nicer, since they have no state).
From a practical standpoint, however, I do create these, and encourage their use when appropriate. Trying to avoid utility classes is often cumbersome, and leads to less maintainable code. However, I do try to encourage my developers to avoid these in public APIs when possible.
For example, in your case, I feel that UrlParser.ParseUrl(...) is probably better handled as a class. Look at System.Uri in the BCL - this handles a clean, easy to use interface for Uniform Resource Indentifiers, that works well, and maintains the actual state. I prefer this approach to a utility method that works on strings, and forcing the user to pass around a string, remember to validate it, etc.
Utility classes are ok..... as long as they don't violate design principles. Use them as happily as you'd use the core framework classes.
The classes should be well named and logical. Really they aren't so much "utility" but part of an emerging framwework that the native classes don't provide.
Using things like Extension methods can be useful as well to align functionality onto the "right" class. BUT, they can be a cause of some confusion as the extensions aren't packaged with the class they extend usually, which is not ideal, but, still, can be very useful and produce cleaner code.
You could always create an interface and use that with dependency injection with instances of classes that implement that interface instead of static classes.
The question becomes, is it really worth the effort? In some systems, the answer in yes, but in others, especially smaller ones, the answer is probably no.
This really depends on the context, and on how we use it.
Utility classes, itself, is not bad. However, It will become bad if we use it the bad way. Every design pattern (especially Singleton pattern) can easily be turned into anti-pattern, same goes for Utility classes.
In software design, we need a balancing between flexibility & simplicity. If we're going to create a StringUtils which is only responsible for string-manipulation:
Does it violate SRP (Single Responsibility Principle)? -> Nope, it's the developers that put too much responsibilities into utility classes that violate SRP.
"It can not be injected using DI frameworks" -> Are StringUtils implementation gonna varies? Are we gonna switch its implementations at runtime? Are we gonna mock it? Of course not.
=> Utility classes, themselve, are not bad. It's the developers' fault that make it bad.
It all really depends on the context. If you're just gonna create a utility class that only contains single responsibility, and is only used privately inside a module or a layer. Then you're still good with it.
I agree with some of the other responses here that it is the classic singleton which maintains a single instance of a stateful object which is to be avoided and not necessarily utility classes with no state that are evil. I also agree with Reed, that if at all possible, put these utility methods in a class where it makes sense to do so and where one would logically suspect such methods would reside. I would add, that often these static utility methods might be good candidates for extension methods.
I really, really try to avoid them, but who are we kidding... they creep into every system. Nevertheless, in the example given I would use a URL object which would then expose various attributes of the URL (protocol, domain, path and query-string parameters). Nearly every time I want to create a utility class of statics, I can get more value by creating an object that does this kind of work.
In a similar way I have created a lot of custom controls that have built in validation for things like percentages, currency, phone numbers and the like. Prior to doing this I had a Parser utility class that had all of these rules, but it makes it so much cleaner to just drop a control on the page that already knows the basic rules (and thus requires only business logic validation to be added).
I still keep the parser utility class and these controls hide that static class, but use it extensively (keeping all the parsing in one easy to find place). In that regard I consider it acceptable to have the utility class because it allows me to apply "Don't Repeat Yourself", while I get the benefit of instanced classes with the controls or other objects that use the utilities.
Utility classes used in this way are basically namespaces for what would otherwise be (pure) top-level functions.
From an architectural perspective there is no difference if you use pure top-level "global" functions or basic (*) pure static methods. Any pros or cons of one would equally apply to the other.
Static methods vs global functions
The main argument for using utility classes over global ("floating") functions is code organization, file and directory structure, and naming:
You might already have a convention for structuring class files in directories by namespace, but you might not have a good convention for top-level functions.
For version control (e.g. git) it might be preferable to have a separate file per function, but for other reasons it might be preferable to have them in the same file.
Your language might have an autoload mechanism for classes, but not for functions. (I think this would mostly apply to PHP)
You might prefer to write import Acme:::Url; Url::parse(url) over import function Acme:::parse_url; parse_url();. Or you might prefer the latter.
You should check if your language allows passing static methods and/or top-level functions as values. Perhaps some languages only allow one but not the other.
So it largely depends on the language you use, and conventions in your project, framework or software ecosystem.
(*) You could have private or protected methods in the utility class, or even use inheritance - something you cannot do with top-level functions. But most of the time this is not what you want.
Static methods/functions vs object methods
The main benefit of object methods is that you can inject the object, and later replace it with a different implementation with different behavior. Calling a static method directly works well if you don't ever need to replace it. Typically this is the case if:
the function is pure (no side effects, not influenced by internal or external state)
any alternative behavior would be considered as wrong, or highly strange. E.g. 1 + 1 should always be 2. There is no reason for an alternative implementation where 1 + 1 = 3.
You may also decide that the static call is "good enough for now".
And even if you start with static methods, you can make them injectable/pluggable later. Either by using function/callable values, or by having small wrapper classes with object methods that internally call the static method.
They're fine as long as you design them well ( That is, you don't have to change their signature from time to time).
These utility methods do not change that often, because they do one thing only. The problem comes when you want to tight a more complex object to another. If one of them needs to change or be replaced, it will be harder to to if you have them highly coupled.
Since these utility methods won't change that often I would say that is not much problem.
I think it would be worst if you copy/paste the same utility method over and over again.
This video How to design a good API and why it matters by Joshua Bloch, explains several concepts to bear in mind when designing an API ( that would be your utility library ). Although he's a recognized Java architect the content applies to all the programming languages.
Use them sparingly, you want to put as much logic as you can into your classes so they dont become just data containers.
But, at the same time you can't really avoid utilites, they are required sometimes.
In this case i think it's ok.
FYI there is the system.web.httputility class which contains alot of common http utilities which you may find useful.
Should my interface and concrete implementation of that interface be broken out into two separate files?
If you want other classes to implement that interface, it would probably be a good idea, if only for cleanliness. Anyone looking at your interface should not have to look at your implementation of it every time.
If there is only one implementation: why the interface?
If there is more than one implementation: where do you put the others?
If by different files you mean different xxx.cs files within your assembly, then normally due to my own practices I would say yes - but this is down to the house standards you use. If you're just programming for yourself, then I would say this is good coding practice, it keeps everything clean and easy to read. The smaller the blocks of code in any given file, the easier something is to follow (within reason), obviously you can start getting into partial classes where things can start getting ridiculous if you don't keep a reign on it.
As a rule, I keep my projects in a logical folder structure where portions of the project might be allocated into folders DAL or BM and within there I might have a number of logically named folders which each contain a number of files: one interface, one implementation and any helper classes specific to those.
However, all that said, your team/in-house best practices should be adopted if you're working within a team of developers.
Separate files... FTW! You might even want to create separate projects/assemblies depending on how extensible your code is. At the very least it should probably be in a separate namespace.
The whole point of an interface is so that the code that uses the interface doesn't care about the implementation. Therefore they should be as loosely associated as possible, which they won't be if they are in the same file.
But as #balabaster notes, it depends on what your team's practices (although they are not always "best practices") are.
Yes, for the classes they're called partial class,
take a look link text
General rule of thumb, yes. An Interface means it may be implemented by other classes, it is cleaner and easier to manager when they are clearly in separate files.
What's more, depending on the level of separation and isolation your application is going to take, you would even want to place your interfaces in its own project. Then consuming projects would reference the interface project instead of each and every assembly that carries implementations of that interface.
Yes, even if one gives counter arguments such as there's only one implementation or he/she foresees that there will be only one implementation for a long time or he/she is the only user/developer, etc. If there are multiple implementations, multiple users, etc, then it's obvious that you would want to keep them in separate files. So why should one treat it differently in the case of one implementation only?