I currently put them in an interface folder but this wont help readability for people who do not know the code base no more than lumping all of your implementation classes in a folder called implementation.
How do you guys logically sort your project interfaces.
I assume you're talking about the kind of interfaces that classes implement in OO languages.
I'd say it's better to name the folder by function, if you really want to separate the interface from implementing classes - call the folder 'listeners' or whatever these interfaces represent. The fact they're interfaces (or abstract classes) should be obvious from the way they're named and used.
Then again, if it's not some form of a framework other people will use, but end up with an interface and a two or three implementing classes you write and leave them be, you might as well stick them all together in the same package. I don't think that making a package for a single class/interface does much for clarity.
Not part of the question but I'll write it anyway - I'm also not a fan of the "I" prefix for interfaces. If it's not obvious without it, then it could probably use a different name/structure.
Related
What is best practice for the directory/location of your interfaces? (as in implements)
in the folder with the class you are interfacing? an interface folder in the source root?
Generally speaking, you shouldn't differentiate between an interface and a class when choosing package structure.
Since you're almost certainly using interfaces to make your API cleaner, you should imagine that you are giving your code to another experienced AS3 coder; where would they expect to find the class/interface within a SWC? There's no reason that they should differentiate between an interface and a class, given that they can't see the code anyway.
This isn't a question with a back-and-white answer. That said, it is my personal opinion that it makes most sense for an interface to live in the same package as the classes which implement it (or as close as possible). That way others who use your code can infer some thing about the interface and its intended use from the package structure.
When all the interfaces are in an "interface" folder on the root 1 - that folder can get really big & ugly, 2 - the interfaces are totally disconnected from all the related files, so it's more difficult to move them around as a group, 3 - your only clue about what the interface does (without actually opening it or importing it and examining its docs and members) is the file name.
I have created a Singleton class that handles my project texts. What is the appropriate name of a Singleton class like this?
TextManager?
TextHandler?
TextController?
Is there a difference in meaning of these names?
UPDATE:
The class stores the project text as xml and have a method for returning the correct text.
function getText(uid : String) : String
I suppose it doesn't deal with adding/removing/... (-> managing) the texts (maybe just loading), so it isn't a "real" Manager.
It also doesn't "control" the texts (something "You're only accessible from ...", "Return another value for that key if ...").
The class provides you with texts.
I suppose it's some Kind of localized text provider, right?
So why don't you call it LocalizedTextProvider?
I usually call something like this
TextUtility
or
TextHelper
the problem with 'handler' is that it implies some sort of event handling. Same thing with 'Controller', it has meaning in a different context.
I believe Controller is 'reserved' for the MVC model but I may be wrong. TextHandler and TextManager may be better but at least at the place I work, 'Manager' in a service/class is generally discouraged since it is assumed that every class 'manages' something (this may just be culture-specific, though).
I'd vote for TextHandler out of those three. It may also depend slightly on your programming language.
This actually sounds like a service or repository to me...
TextService or TextRepository? TextModel?
But let me back up a bit... the Singleton pattern is a pretty bad way of accessing something like this. Just google "Singleton pattern problems" if you want to see what I am talking about. Plus, in AS3, you don't have private constructors so you can't implement the Singleton pattern in a pure way.
Instead, I really prefer composition via "Inversion of Control" (IoC) containers. There are plenty of them out there for ActionScript. They can be really lightweight but they decouple your components in a really elegant way.
Sorry to inject my thoughts here... ymmv :)
EDIT -- More on eliminating Singleton pattern
I have written about several strategies on eliminating singletons in your code. This article was written for C#, but all the same principles apply. In that article, I DON't talk explicitly about IoC containers.
Here is a pretty good article about IoC in Flex. In addition, several frameworks give you IoC capabilities:
Swiz
Robot Legs
fling
Cairngorm
flex-ioc
All three of the names you proposed can all be interpreted in the same way. Some people prefer handlers while others might say controllers... it really is a matter of semantics. Whatever convention you choose to adopt just be consistent. The common notion that you should capture though is that the class which you are describing is not doing anything. It should only be in charge of delegating, since that's what managers do to employees and controllers do in the classic MVC paradigm.
As I usually have Handler in the event/message handling context. Controller for actions and MVC stuff, I would go with something different:
TextResources.get(key)
I18n.get(key) (if your class is in fact used for internationalisation)
I usually reserve Helpers for classes allowing to simply transform some data into something to be used in the view.
TextCache? Sounds like you are just using it to store and retrieve data...
Why not : ProjectNameTexts
FooTexts.getInstance().getText('hello_world');
I've noticed that some programmers like to make interfaces for just about all their classes. I like interfaces for certain things (such as checking if an object supports a certain behavior and then having an interface for that behavior) but overuse of interfaces can sometimes bloat the code. When I declare methods or properties as public I'd expect people to just use my concrete classes and I don't really understand the need to create interfaces on top of that.
I'd like to hear your take on interfaces. When do you use them and for what purposes?
Thank you.
Applying any kind of design pattern or idea without thinking, just because somebody told you it's good practice, is a bad idea.
That ofcourse includes creating a separate interface for each and every class you create. You should at least be able to give a good reason for every design decision, and "because Joe says it's good practice" is not a good enough reason.
Interfaces are good for decoupling the interface of some unit of code from its implementation. A reason to create an interface is because you foresee that there might be multiple implementations of it in the future. It can also help with unit testing; you can make a mock implementation of the services that the unit you want to test depends on, and plug the mock implementations in instead of "the real thing" for testing.
Interfaces are a powerful tool for abstraction. With them, you can more freely substitute (for example) test classes and thereby decouple your code. They are also a way to narrow the scope of your code; you probably don't need the full feature set of a given class in a particular place - exactly what features do you need? That's a client-focused way of thinking about interfaces.
Unit tests.
With an interface describing all class methods and properties it is within the reach of a click to create a mock-up class to simulate behavior that is not within the scope of said test.
It's all about expecting and preparing for change.
One approach that some use (and I'm not necessarily advocating it)
is to create an IThing and a ThingFactory.
All code will reference IThing (instead of ConcreteThing).
All object creation can be done via the Factory Method.
ThingFactory.CreateThing(some params).
So, today we only have AmericanConcreteThing. And the possibility is that we may never need another. However, if experience has taught me anything, it is that we will ALWAYS need another.
You may not need EuropeanThing, but TexasAmericanThing is a distinct possibility.
So, In order to minimize the impact on my code, I can change the creational line to:
ThingFactory.CreateThing( Account )
and Create my class TexasAmericanThing : IThing.
Other than building the class, the only change is to the ThingFactory, which will require a change from
public static IThing CreateThing(Account a)
{
return new AmericanThing();
}
to
public static IThing CreateThing(Account a)
{
if (a.State == State.TEXAS) return new TexasAmericanThing();
return new AmericanThing();
}
I've seen plenty of mindless Interfaces myself. However, when used intelligently, they can save the day. You should use Interfaces for decoupling two components or two layers of an application. This can enable you to easily plug-in varying implementations of the interface without affecting the client, or simply insulate the client from constant changes to the implementation, as long as you stay true to the contract of the interface. This can make the code more maintainable in the long term and can save the effort of refactoring later.
However, overly aggressive decoupling can make for non-intuitive code. It's overuse can lead to nuisance. You should carefully identify the cohesive parts of your application and the boundaries between them and use interfaces there. Another benefit of using Interfaces between such parts is that they can be developed in parallel and tested independently using mock implementations of the interfaces they use.
OTOH, having client code access public member methods directly is perfectly okay if you really don't foresee any changes to the class that might also necessitate changes in the client. In any case, however, having public member fields I think is not good. This is extremely tight coupling! You are basically exposing the architecture of your class and making the client code dependent on it. Tomorrow if you realize that another data structure for a particular field will perform better, you can't change it without also changing the client code.
I primarily use interfaces for IoC to enable unit testing.
On the one hand, this could be interpreted as premature generalization. On the other hand, using interfaces as a rule helps you write code that is more easily composable and hence testable. I think the latter wins out in many cases.
I like interfaces:
* to define a contract between parts/modules/subsystems or 3rd party systems
* when there are exchangeable states or algorithms (state/strategy)
In your object-oriented language, what guidelines do you follow for grouping classes into a single file? Do you always give each class a seperate file? Do you put tightly coupled classes together? Have you ever specified a couple of implementations of an interface in one file? Do you do it based on how many lines of code the implementation might be or how "cluttered" it might look to the user of the class? Or would the user prefer to have everything on one place?
Personally, I suggest one class per file unless the secondary classes are private to the primary class in the file. For example, a nested class in C# would remain in the parent classes file, but utility classes that might be useful elsewhere get broken into their own file or even namespace.
The key is to understand your environment and where people will look for things. If there is an established methodology in place, think carefully before you upset it. If your coworkers expect that related, tightly bound classes will be in a single document, having to search for them could be annoying (although with modern IDEs it shouldn't be a problem).
An additional reason for breaking things into more files rather than less is version control. If you make a small change, it should change only a small file where possible. If you make a sweeping change, it is obvious looking at the logs because of all the files (and indirectly, classes) that were affected are noted.
I think best practices in all OO languages I have ever used is to have one class in one file. I believe some languages may require this but I am not sure of that fact. But I would say that one class per file, and the name of the file matching the name of the class (as well as the directory structure matching the package structure for the most part) is best-practice.
1 class = 2 files. An .h and a .c, you kids are so lucky :)
There is no hard and fast rule that must always be followed (unless a particular language enforces it). There are good reasons for having just one class, or having multiple classes in a file. And it does depend on the language.
In C# and Java people tend to stick to one file per class.
I'd say in C++ though I often put multiple classes in one file. Often those classes are small and very related. Eg. One class for each message in some communications protocol. In this case a file for each would mean a lot of files and actually make maintenance and reading of the code more difficult than if they were in one file.
In C++ the implementation of a class is separate from the class definition, so each class { /body/ } is smaller than in other language and that means classes are more conveniently sized for grouping together in one file.
In C++ if you're writing a library (eg the standard template library) , you can put all the classes in one file. Users only need to include the one header file and they get all the classes then, so its easier for them to work with.
There's a balance. The answer is whatever is most easy to comprehend and maintain. By default it makes sense to have one class per file, but there are plenty of cases when it's more practical to work with a related set of classes if they are defined in one file.
I put classes into the same file if they belong together, either for techinical or aesthetic reasons. For example, in an application that provides a plugin interface, the classes Plugin (base class for plugins) and PluginManager I would usually put together in the same file. However, if the file grows too big for my taste, I would split them into separate file.
I note that I write code mostly in Python at the moment, and this influences my design. Python is very flexible in how I get to divide stuff into modules, and has good tools for managing the name spaces of things. For example, I usually put all the code for an application in a Python module (a directory with __init__.py) and have the module import specific names from sub-modules. The API is then something like applib.PluginManager rather than applib.pluginstuff.PluginManager.
This makes it easy to move things around, which also allows me to not be so fussy when I am creating the design: I can always fix things later.
One class = one file. Always. Apart from when one class = multiple files in C#, or a class contains inner classes etc of course ;)
One per a file is our standard. The only exception is that for a class and it's typed collection we put those together.
Over time I've come to relize, that "small class" always tend to grow. And then you'll want to split them up, confusing everyone else on the team (and your self).
I try to keep one class per file (like most of the above), unless they are small classes. If there are a lot of them, I may split them into subjects otherwise. But usually I just keep them all in one file with code-folding in editors. For my private hacks, it just isn't worth the (minimal) effort to me.
One class per file seems to be the standard. This is the way that I usually do it as well.
There have been a few times where I've strayed away from this. Particularly when a smaller class is a member of another class. For example, when designing a data structure, I would likely implement a "node" class within the same file as the "bigstructure" class.
In your object-oriented language, what guidelines do you follow for grouping classes into a single file?
It depends. In team work I try to follow team standards; in solo work I tend more towards whatever-I-please.
In solo work, then ...
Do you always give each class a seperate file? Do you put tightly coupled classes together? Have you ever specified a couple of implementations of an interface in one file?
No. Sometimes. Yes.
Do you do it based on how many lines of code the implementation might be or how "cluttered" it might look to the user of the class? Or would the user prefer to have everything on one place?
It's mostly based on:
How easy is it to navigate? A huge long source file, with many classes, is more difficult.
How easy is it to edit? When editing multiple, short, related classes, it may be easier if they're all in one source file with a splitter than if they're in several source files, given that I run my text editor maximized showing one source file at a time.
I prefer 1 to 1 for classes unless the inner class will be entirely private.
Even then I usually break it out for ease of finding it and tracking changes in SVN.
I remember reading once (I believe the book was the .NET Framework Design Guidelines) that when you are designing a framework or class library that you should take care in how you arrange the classes in your namespaces. Specifically, classes in parent namespaces should have no knowledge of classes in child namespaces. Conversely, it is perfectly alright for classes in the child namespaces to know about the classes in namespaces above them.
For example, the classes in the System namespace don't know anything about the classes in the System.Data.SqlClient namespace. However, classes in System.Data.SqlClient know about the classes in System and in System.Data.
Now, taken at face value, this is a pretty straightforward idea. But there are occasions where this isn't as easy to implement as you might think. Classes are inherently coupled to one another by their very nature. For example:
A business class
The data entity class
The class that maps a data entity class to a business object class
The classes that serialize the data entity to and from the database
Granted, you can separate these into separate, discrete classes that clearly isolate the data and functionality; that isn't my problem. My problem is how to properly arrange them into namespaces that observe best practices for namespaces.
This has always seemed a bit murky to me. I've never seen it clearly addressed, and most samples I've seen have simply placed the data objects off the root namespace (MyProject.DataObjects) or something similar. It's as if noone is really sure, so we just don't talk about it.
I can see that, within the .NET Framework itself, classes reach across namespace boundaries all the time to access the functionality they need. Classes frequently access functionality from System.Collections, System.Collections.Generic, System.Runtime, System.Configuration, System.Reflection, and so on.
It's as if there's an unspoken rule that states that, when it comes to namespaces, "You can't know anything about your own children, but you can know all there is to know about the children of your grandparents, aunts, uncles, neices, nephews, and cousins." This guideline seems counter-intuitive and senseless to me; it seems to complicate namespace design.
So Here's the Question
How do you design namespaces in your own large applications? Are you really all that concerned about preserving namespace boundaries? If so, how do you resolve issues where classes are clearly related (despite having been decoupled as much as you can manage)?
I'm really interested in your experiences, and your input on this. It's been bugging me for a while now. If you could provide an example of namespace arrangement for a 3-tier application that included business objects, data entities, and so on, it'd be great. I'd really like to see how you guys arrived at your namespace models, and why.
Thanks very much in advance!
If you have two tightly inter-related classes, you just put them in the same namespace.
I see namespaces as being for holding related classes, functions, enums, etc., so this should be quite natural.
Now it might be the case that some namespaces naturally build on items in other namespaces. But if two classes are so closely related as to build on each other, I'm not sure why I would even consider putting them in different namespaces. There's probably a good reason, but I've never come across it.