Ok, the title might sound a bit vague but I really can't think of something clearer here.
I recently was in the position where I needed a Point class, simply with two properties, X and Y and a ctor Point(int x, int y). Nothing fancy. Now this thing already exists in .NET, but this was in a library that handled certain objects on a map and dragging System.Drawing into this just felt ... wrong somehow. Even though System.Drawing.Point fit what I needed perfectly, I now created that struct myself again in that project.
Now I wonder whether that was a right or sensible thing to do. System.Drawing.Point would have come with a reference to that assembly as well, if I remember correctly. And putting something in System.Drawing into a totally non-drawing related context was somehow weird.
Thoughts? What if it wouldn't have implied a reference to another assembly?
I disagree with the other answers so far and say that it actually matters. The Point sample is a simple one, but in general using a class in a context it hasn't been designed for may have undesired effects.
A class may have been implemented for a particular use case only, e.g. no support for thread safety, requiring the use within a framework or exposing functionality that is unwanted in your code.
It might especially lead to problems when a newer version of the assembly is deployed, which is no longer compatible with the way that you use it, or the newer version brings additional members and dependencies that you don't want to have in your code.
The context of namespace is fundamental in approaching the precise function of a class; a Connection class is going to be a very different beast from one namespace to the next. Is a Web.Cache class going to be suitable for caching in other applications, or does it have a fundamental dependency on web infrastructure?
MSDN describes System.Drawing.Point structure as follows:
"Represents an ordered pair of integer x- and y-coordinates that defines a point in a two-dimensional plane."
With such a general description, it could be argued that this structure is only incidentally related to drawing and really belongs in a more fundamental namespace.
However, as it does live in System.Drawing, the implication is that it represents a point within a 2-dimensional drawing space. As such, using it for purposes other than drawing is mis-use of the class; it may function for your needs, but it is not being used for its original purpose.
I wouldn't say that what you did was wrong however a namespace is really just a container for declarations within which each name is unique, the namespace name does provide some context to help you find the right function for your need but don't get hung up on the context not quite fitting your useage, if the object is ideal then it's ideal. Apart from the using statement you will probably never actively refer to the namespace again.
If your purpose for the point was in no way drawing related, I think you did the right thing. Using a System.Drawing.Point in code which does nothing drawing related at all may confuse people down the line into thinking it's used for some drawing functionality.
I was in a similar situation recently. Not needing the Point class, but I'll use that as an example.
I made my own Point class because the System.Drawing.Point uses ints, when I needed doubles. I realised later that it was a good idea, even if I only needed ints because I can then extend the class as needed, and add methods, interfaces and attributes etc. Whereas I wouldn't have been able to should I have used the System.Drawing.Point.
There's the principle that you should not duplicate knowledge in your programs, but in some cases such as this one, it can't be avoided.
As for implying reference to another assembly, you can do this:
using Point = System.Drawing.Point; // or whatever your namespace is called
I would have just used the System.Drawing.Point. Why re-create something that already exists? Who cares what the namespace is called if provides the functionality you need. Just my 2 cents...
If you're not importing any "luggage" (like having to intialize stuff that you don't use) so it's exactly what you need, I'd go for the existing code. Just no point in recreating existing code. Chances are also that you may discover functions later on which perform functions you need and expect that particular class.
Still, I can identify with feeling strange having an "alien" object in your code. One way to get around this would be to subclass it with your own point. That'll look a bit strange if you're not changing anything in your subclass, but that's only visible in the source of that class, and where you use it, it's consistently named. Also it'll start looking actually smart as soon as you find yourself adding functionality to your custom Point.
I would worry very little about bringing something in from the namespace given that both functionally and conceptually (how it is described in the docs) it fits the goal.
I might hesitate to bring in a new assembly though. In this case the fact that Point is so quick to roll ones own that I might consider the hassle of doing so less than that of adding another dependency to the assembly I was writing.
Otherwise, as long as I wasn't using it as a Key (the GetHashCode impl. in point isn't great in the way it collides for e.g. all of {0,1},{1,0},{2,3}and{3,2} if you have a lot of low-valued or rectanguarly distributed points) I'd use it.
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
I'm writing an XNA engine and I am storing all of the models in a List. In order to be able to use this throughout the engine, I've made this a public static List<Model> so I can access it from any new classes that I develop. It certainly makes obtaining the list of models really easy to get too, but is this the right usage? Or would I be better off actually passing a variable through in a method declaration?
In OOP it's generally advisable to avoid using static methods and properties, unless you have a very good reason to do so. One of the reasons for that is that in the future you may want to have two or more instances of this list for some reason, and then you'll be stuck with static calls.
Static methods and properties are too rigid. As Stevey states it:
Static methods are as flexible as
granite. Every time you use one,
you're casting part of your program in
concrete. Just make sure you don't
have your foot jammed in there as
you're watching it harden. Someday you
will be amazed that, by gosh, you
really DO need another implementation
of that dang PrintSpooler class, and
it should have been an interface, a
factory, and a set of implementation
classes. D'oh!
For game development I advocate "Doing The Simplest Thing That Could Possibly Work". That includes using global variables (public static in C#), if that is an easy solution. You can always turn it into something more formal later. The "find all references" tool in Visual Studio makes this really easy.
That being said, there are very few cases where a global variable is actually the "correct" way to do something. So if you are going to use it, you should be aware of and understand the correct solution. So you can make the best tradeoff between "being lazy" and "writing good code".
If you are going to make something global, you need to fully understand why you are doing so.
In this particular case, it sounds like you're trying to trying to get at content. You should be aware that ContentManager will automatically return the same content object if you ask for it multiple times. So rather than loading models into a global list, consider making your Game class's built-in ContentManager available via a public static property on your Game class.
Or, better still, there's a method that I prefer, that I think is a bit better: I explain it in the answer to another question. Basically you make the content references private static in the classes that use them and pass the ConentManager into public static LoadContent functions. This compartmentalises your use of static to individual classes, rather than using a global that is accessed from all over your program (which would be difficult to extricate later). It also correctly handles loading content at the correct time.
I'd avoid using static as much as possible, over time you'll just end up with spaghetti code.
If you pass it in the constructor you're eliminating an unnecessary dependency, low coupling is good. The fewer dependencies there are, the better.
I would suggest to implement a Singleon object which encapsulates the model list.
Have a look at the MSDN singleton implementation.
This is a matter of balance and trade-offs.
Of course, OOP purists will say that avoid such global variables at all costs, since it breaks code compartmentization by introducing something that goes "out of the box" for any module, and thus making it hard to maintain, change, debug etc.
However, my personal experience has been that it should be avoided only if you are part of a very large enterprise solutions team, maintaining a very large enterprise-class application.
For others cases, encapsulating globally-accessible data into a "global" object (or a static object, same thing) simplifies OOP coding to a great extent.
You may get the middle-ground by writing a global GetModels() function that returns the list of models. Or use DI to automatically inject the list of models.
If I'm dealing with one class and one public struct (not nested), Should I create a separate .cs just for the struct? Or leave it un-nested in its .cs file of the class? (This is assuming the struct relates to the class, but isn't so exclusive to the class that it should be nested and declared private)
Edit: I removed my initial question about two classes because I found C# classes in separate files?
Note that the only person(s) that can accurately answer this question is you, and your team. If your team is happy to find several related types inside a single file, combined due to ... whatever... then what I, or whomever other person, says, should be just ... irrelevant.
In any case, I would turn the question upside down:
Is there any reason to place two separate types (related by names, functionality, or whatever, but separate nonetheless) in the same file
and I've yet to come up with a good reason.
There are extensions/addins to Visual Studio where you can type in the name, and quickly navigate to the file, and I can think of three, but there are undoubtedly others:
DPack
ReSharper
CodeRush/Refactor! Pro
The first allows you to quickly navigate to a file by name. If you know the type, but have people putting multiple types into the same type, this will not be helpful, at all.
The second and third, lets you navigate to a type by name, but you shouldn't rely on people having those, or knowing how to use them.
To that end, I would advocate following these rules:
Project names should be identical to the root namespace of that project. I differ from this point myself where in some cases I name my projects "...Core", and I then remove "Core" from the namespace, but otherwise, leave the project name identical to the namespace
Use folders in the project to build namespace hierarchies
The name of a type should correspond 100% to the name of the file + whatever extension is right for your language. So "YourType" should be "YourType.cs", "YourType.vb" or "YourType.whatever" depending on language
That depends on who you ask.
I, personally, find it easier to read if they are all, always, broken out. However, the compiler doesn't care... so whatever you and your team agree is easier to understand.
In my opinion it's a good practice to avoid that. Some day a developer will be looking around for ClassBar in the project and won't be able to find it easily because it's nested in ClassFoo.cs
Tools like Resharper have a neat feature where you can just select a class, right click, place in new file to make this easier.
If you read any of the popular coding standards (Lance Hunt, iDesign, Framework Design Guidelines etc) most of them advocate 1 class per file.
Its annoying to scroll down and search for how many class each.cs file contains/hides.
Maintainability issue while using version control
Usability with our team.
Check here for more interesting discussion on same.
I think it was less about whether you can or whether you should. For things like this, I feel it's best to look to the convention in the rest of the codebase. Sometime conformity is better because it makes other developers jobs easier becaues everybody knows where things are.
If it's entirely new project and you are setting the standards here by yourself, do what makes sense to you. To me if the struct has no use outside the related class, I may put them in the same file. Otherwise, I seperate them out.
I am building a class library and using its default namespace as "System". There suppose I am creating a generic data structure say PriorityQueue and putting it under System.Collections.Generic namespace.
Now when I am referencing that library from another project, I can't see PriorityQueue under "System.Collections.Generic" namespace anymore. Though the library is referenced I can not access any of the classes in it.
Can anyone shed some light on it please. I know that if I change the namespace everything will be ok, but I want to create a seamless integration like .net framework itself with other project, so that one can refer the library and forget about its namespaces.
This is a very bad idea. Pretend you didn't think it up, and use a real namespace.
One does not have "seamless integration" with the .NET Framework, either. If we want to access the List<T> class, then we have to write
using System.Collections.Generic;
If you put your class in MyCompany.Collections.Generic, then you'll get exactly the same level of "seamlessness" that is achieved by the .NET Framework itself.
If you are using the System namespace for your classes, then they will be found in System.
If you want them to be found in System.Collections.Generic, then you need to place them there.
But let's be clear, placing classes in System.* is a bad idea.
Putting stuff in system namespaces is a bad idea. Firstly it's better to know explicitly where the stuff your using is. However more importantly, if Microsoft releases new stuff that causes a naming conflict with yours, your stuff breaks.
The second reason is probably why you cant see your code.
Just create your own namespace, e.g. Anindya.Collections.Generic, as placing classes in predefined framework namespaces isn't a good idea. MS might introduce a same class in a later framework, leading to problems.
Did somebody mention yet that this is a bad idea? There are few reasons you wouldn't be able to see the class. Short from the assembly reference, there is only one good one: you forgot to declare the class public.
In case it wasn't clear: This is a REALLY bad idea.
The System name space should be considered reserved and verboten. If Microsoft decides to introduce a class in a framework update that conflicts with your System.mycrap.blah identifier in the future, you're going to have some pretty hefty refactoring on your hands, and, in the case of an app that's deployed to a client, an emergency update and potential liability for system downtime.
You wouldn't create your own class called "String." By the same token (pun), don't use reserved namespaces.
Also, the namespace "System" doesn't really describe the contents of your namespace. Typically, namespaces should mean something - like, BlogEngine, DatabaseCore, etc. Slapping everything into System is a lot like naming all of your variables "x," or "temp," and implies that the creator doesn't really understand the point of this level of code delineation and organization.
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)