I would like to separate the API I'm working on into two sections: 'bare-bones' and 'cushy'. The idea is that all method calls in the 'cushy' section could be expressed in terms of the ones in the 'bare-bones' section, that is, they would only serve as convenience methods for the quick-and-dirty. The reason I would like to do this is that very often when people are beginning to use an API for the first time, they are not interested in details and performance: they just want to get it working.
Anybody tried anything similar before? I'm particularly interested in naming conventions and organizing the code.
One way to provide a discrete separation of 'cushy' vs 'bare-bones' would be using separate interfaces that are implemented by the same class. When writing an API I like to keep it as simple as possible. If you need lots of parameters, consider using a fluent interface.
Yes, I've done something like this before, and I tend to pre-pend a word that indicates what the extra functionality is doing.
For example, a basic Vector class might only perform very basic vector operations (add, dot product), and a Vectors class might have a variety of static helper methods (cross products, projections, etc). Then, a FluentVector incorporates all those helper operations, while mutating the underlying Vector.
However, this isn't the decorator pattern - decorator produces different "decorated" results with the same interface. This is the facade pattern - different interface with the same underlying function.
Also, keep in mind that your extended API may have a variety of different ways of delivering the same function. Back to my Vector example, one might not want to mutate the underlying Vector with each chained-operation and instead introduce a new Vector - this might be an ImmutableFluentVector or some such. The API would be identical, except for the specification of side-effects. Just something to keep in mind.
Since you're asking for nice names, commonly used is simple or basic API and extended API. The simple API uses, as mentioned by Simon Nickerson, the extended API technically by providing an abstraction. See also Facade Pattern
Assuming Barebone provides basic functionality and Cushy provides additional functionality:
public class Skeleton
{
public virtual void Info()
{
}
}
public class Adorner:Skeleton
{
private Skeleton _skeleton;
public Adorner(Skeleton skeleton)
{
_skeleton = skeleton;
}
public override void Info()
{
//apply adorning work
}
}
Skeleton bareBones = new Skeleton();
Adorner cushy = new Adorner(bareBones);
Somebody at work suggested Foo and FooHelper. I like it.
Related
I'm trying to figure out a class design for a library that operates on a weighted graph. Various algorithms may be performed on this graph, for example, finding the shortest distance between two nodes, the longest distance between two nodes, the number of paths of between two nodes where the distance is less than 10 (say), etc.
My concern is NOT how to implement the algorithm or the data structures for the graphs as I know how to do this, rather it is on the overall high-level class design. The point being that in the future we may want to add other algorithms, so the solution should be easily extensible. One option for implementing is just to write a single class that has methods for implementing each of these algorithms. Then in the future additional methods can be added to this class for any new algorithms.
public class GraphCalculator
{
Graph _graph;
public int GetLongestDistance(string startPlaceName, string endPlaceName)
{
}
public int GetShortestDistance(string startPlaceName, string endPlaceName)
{
}
public int GetNumberOfPaths(int minimumDistance)
{
}
//any new algorithms will be implemented as new methods added to this class
}
My concern is that this violates the SOLID Open/Closed principle. Should each algorithm instead be implemented in its own class? If so, what is the recommended class structure to achieve this, so that it is loosely coupled and easily testable, and how would it be called from the public API layer? Are there any recommended design patterns for this?
The answer to your question Should each algorithm instead be implemented in its own class is definitely yes! You are stating, that you want easily extensible solution. A single class that has methods for implementing each of these algorithms. Then in the future additional methods can be added to this class for any new algorithms. it not extensible at all! Your are changing the code and you need to modify your current base implementation! This is exactly the opposite of the OOP principle - closed for modification, but open for extension!
Every single algorithm you have to implement (at present or in future) is a behaviour and should be defined using an interface. All implementations should implement this common interface. This way you will also be able to test every single algorithm implementation easily on its own. This allows you also to define one list of algorithms, that is easily maintained dynamically (via code or configuration). Considering all this, what you need is some kind of a plug-in architecture.
One design pattern that matches your need could be the Visitor pattern, since it adds new operations (= algorithms like shortest path, longest path, etc.) to existing data structures (graph object).
Another option could be the PlugIn design pattern, although IMO this pattern could be more challenging to implement than the visitor. If it is alright to use 3th party software and existing frameworks, you could have a look at the Sprint plugin project, that uses the Spring framework and defines a pluggable architecture helper. A (somewhat) similar solution for .NET is the Managed Extensibility Framework and/or the Enterprise Library - Unity Application Block.
Why does it have to it's own class to begin with? It doesn'T do anything useful on it's own, just wrapping the Graph instance and up to know all it does offer are functions over an Graph. Have you considered making them static functions in a helper class where all relevant parameters are passed into instead?
Or you might consider the Strategy Pattern if you want to make the implementations interchangable.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 8 years ago.
Improve this question
I have a very simple task in Java, and I am not sure which structure to give to my project.
I want to create a little project in Java, that makes some statistical calculations. For example, I will need to create a method that gets an array, and returns the mean, another method gets an array, and returns a standard deviation, I will also need a method that gets two arrays, and returns the correlation coefficient.
What I want to know, is how to do this now that I have opened a new project in Eclipse ?
Should it all be in one class ? Should I have a separate class for each method, making it a static method ? At the end, I want to give this code for someone else to integrate it in his project. I need to do it as simple and efficient as possible.
Can you please guide me on how to do it ? One class, several classes ? Public / private ? I am not familiar with these things, but I can program the methods themselves.
Thank you in advance
All your methods have the following attributes:
That they don't possibly have another implementation as long as your give them specific enough names. After all mathematical doesn't change. This means you don't possibly need structure like interfaces or subclasses.
That when people use them they have tendency to use several of them or group by functionality. That means you should group your methods by usage e.g. statistical methods; signal processing methods; and so on.
That the methods don't keep internal status and all the output is returned without any side effect of other callers/threads. Thus your methods don't have to have class contain themselves or any statue variables.
That your methods essentially provider utility to the main program but the semantics of the methods doesn't vary due to the caller or calling context.
So as all the above shows, your methods should be inside 1 or several classes as grouped by their nature or usage. The methods should be static methods without any side effect. That's exactly what java.lang.Math does.
I want to create a little project in Java, that makes some statistical calculations. For example, I will need to create a method that gets an array, and returns the mean, another method gets an array, and returns a standard deviation, I will also need a method that gets two arrays, and returns the correlation coefficient.
Looks to me that you are interested in creating a utility class for statistical calculation. The scope of how to achieve is this quite broad but it is advised to follow common coding conventions and basic OOP concnepts.
Should it all be in one class ? Should I have a separate class for each method, making it a static method ?
Since each of the methods ( mean, standard deviation ...) are related to the same core background (i.e to perform some statistical calculation), it seems logical to have a single utility class with a separate static methods for each of the function that you need to create.
Of-course you will have to take care of the basic OOP concepts like (data hiding) keeping the fields private and exposing them properly public getter/setters. Also, it would be a good idea to keep your calculation methods private and just exposing a public method which calls your private functions. Something like
public class MyUtilityClass{
// A bunch of private fields
int field1; ...
private MyUtilityClass(){} // We don't want anyone to create an object of this class
// method exposed to user
public static float calcArithmeticMean(float[] arr1, float[] arr2){
return getMean(arr1, arr2);
}
// method for internal use
private float getMean(float[] f1, float[] f2){
//do your calculation here
}
// remember to expose only those fields that you want the user be able to access
// getter/setters here
}
At the end, I want to give this code for someone else to integrate it in his project.
If you follow proper OOP coding conventions, then your utility class will be portable and anyone will be able to understand and extend it in their application.
I would create a single class representing the array of numbers itself.
public class DataSet extends HashSet<Double> {
public double mean () {
// implementation
}
public double standardDeviation () {
// implementation
}
public double correlationCoefficient (DataSet other) {
// implementation
}
}
My first suggestion is to start your project using Maven. It gives you a solid project structure with a great tool to manage your jar file dependencies and build lifecycle. In addition, all major Java IDEs, including Eclipse, easily create, understand and use your Maven settings.
Secondly, for your application design, it is recommended to avoid using lots of static methods because they hurt testability of your code as for example explained here.
Regarding the number of classes and methods, it depends on your specific use case but the guideline is to try to aggregate similar methods, based on their responsibilities, in one class while separating classes if there are too many responsibilities being handled by a single class. Low coupling and high cohesion are your friends in this case.
Arrays may be slightly faster than collections but be careful with them because they are reifiable and do not mix well with generics. Generally, rely on Collections. Also, if you can use Java version 8, have a look at Streams API.
Last but not least, Java has tons of open source code out there. So, always look for a library before starting to write one. In case of Math, have a look at this and that.
Create one class with a different methods with public access for each calculation type(one method for each of mean, standard deviation and so on). These methods can internally refer to helper methods in another utility class(es) not publicly accessible, as per your convenience.
Put all these classes in a single package and export it for integrating in other projects.
Since it will be used by others as a library by others , make sure you document and comment it as much as possible.
I vote for single class. The methods should be static and the parameters that you don't want to show should be private.
It depends on many thing such as other part of project, future changes and extensions,...
I suggest to start with single-class/public-static and change it in demand when you expand the project.
I'm working with a Java API used for "macros" that automate a piece of software. The API has, among other things, the classes Simulation (a global state of sorts) and FunctionManager. There's nothing I can do to modify these classes.
I'd like to make a BetterFunctionManager class that extends FunctionManager because the latter lacks some useful features. But I don't know how to do this, because FunctionManager can't be instantiated directly. It must be gotten from Simulation, like this:
Simulation simulation = getCurrentSimulation();
FunctionManager functionManager = simulation.getFunctionManager();
Note that Simulation can't be instantiated directly either; it must be gotten via getCurrentSimulation() (the current simulation is determined at runtime by the macro interpreter).
I can't downcast; the following throws a ClassCastException:
BetterFunctionManager betterFunctionManager = simulation.getFunctionManager();
How can I construct BetterFieldFunctionManager?
Disclaimer: I am still very naive about designing. Just a suggestion. use delegation design pattern
public class BetterFunctionManager{
private FunctionManager fm;
public BetterFunctionManager(FunctionManager fm){
this.fm = fm;
}
existingMethods(){
fm.existingMethods();
}
newMethods(){
// new implementation
}
}
Disadvantages:
need to wrap all methods of FunctionManager
Advantage:
there is no need to change in any other place . just change like
BetterFunctionManager betterFunctionManager =
new BetterFunctionManager (simulation.getFunctionManager());
What you have found is known as The Expression Problem and I'm afraid your most reasonable option to attack it with pure Java is StinePike's proposal of using composition and delegation
If you are in position to choose the tool for the task then I'd recommend you to take a look at Clojure Protocols. They offer a really nice solution to the expression problem (see very good explanation here Solving the Expression Problem with Clojure) and if I'm not mistaken if you end up coding your solution in clojure you can compile it into a java .class and use it in your java app
As your options are limited due to the class structures, how about creating a FunctionManagerUtility class instead of BetterFunctionManager. In FunctionManagerUtility class you can add methods to add your useful features by taking FunctionManager object as an input.
By now my average class contains about 500 lines of code and about 50 methods.
IDE is Eclipse, where I turned “Save Actions” so that methods are sorted in alphabetical order, first public methods, and then private methods.
To find any specific method in the code I use “Quick Outline”. If needed, “Open Call Hierarchy” shows the sequence of methods as they called one by one.
This approach gives following advantages:
I can start typing new method without thinking where to place it in the code, because after save it will be placed by Eclipse to appropriate place automatically.
I always find public methods in the upper part of the code (don’t have to search the whole class for them)
However there are some disadvantages:
When refactoring large method into smaller ones I’m not very satisfied that new private methods are placed in different parts of code and therefore it’s little bit hard to follow the code concept. To avoid that, I name them in some weird way to keep them near each one, for example: showPageFirst(), showPageSecond() instead of showFirstPage(), showSecondPage().
May be there are some better approaches?
Organize your code for its audiences. For example, a class in a library might have these audiences:
An API client who wants more detail on how a public method works.
A maintainer who wants to find the relevant method to make a small change.
A more serious maintainer who wants to do a significant refactoring or add functionality.
For clients perusing the source code, you want to introduce core concepts. First we have a class doc comment that includes a glossary of important terms and usage examples. Then we have the code related to one term, then those related to another, then those related to a third.
For maintainers, any pair of methods that are likely to have to change together should be close by. A public method and its private helper and any constants related to it only should show up together.
Both of these groups of users are aided by grouping class members into logical sections which are separately documented.
For example, a collection class might have several mostly orthogonal concerns that can't easily be broken out into separate classes but which can be broken into separate sections.
Mutators
Accessors
Iteration
Serializing and toString
Equality, comparability, hashing
Well, naming your methods so that they'll be easier to spot in your IDE is really not good. Their name should reflect what they do, nothing more.
As an answer to your question, probably the best thing to do is to split you class into multiple classes and isolate groups of methods that have something in common in each of such classes. For example , if you have
public void largeMethodThatDoesSomething() {
//do A
//do B
//do C
}
which then you've refactored such that:
public void largeMethodThatDoesSomething() {
doA();
doB();
doC();
}
private void doA() {};
private void doB() {};
private void doC() {};
you can make a class called SomethingDoer where you place all these 4 metods and then use an instance of that class in your original class.
Don't worry about physically ordering your methods inside the class, if you can't see it just use Ctrl-O and start typing the method name and you will jump straight to it.
Having self-describing method names results in more maintainable code than artificially naming them to keep them in alphabetical order.
Hint: learn your shortcut keys and you will improve your productivity
Organizing the way you described sounds better than 99% of the Java code I have seen so far. However, on the other side, please make sure your classes don't grow too much and methods are not huge.
Classes should usually be less than 1000 lines and methods less than 150.
I've just come across a pattern I've seen before, and wanted to get opinions on it. The code in question involves an interface like this:
public interface MyCrazyAnalyzer {
public void setOptions(AnalyzerOptions options);
public void setText(String text);
public void initialize();
public int getOccurances(String query);
}
And the expected usage is like this:
MyCrazyAnalyzer crazy = AnalyzerFactory.getAnalyzer();
crazy.setOptions(true);
crazy.initialize();
Map<String, Integer> results = new HashMap<String, Integer>();
for(String item : items) {
crazy.setText(item);
results.put(item, crazy.getOccurances);
}
There's reasons for some of this. The setText(...) and getOccurances(...) are there because there are multiple queries you might want to do after doing the same expensive analysis on the data, but this can be refactored to a result class.
Why I think this is so bad: the implementation is storing state in a way that isn't clearly indicated by the interface. I've also seen something similar involving an interface that required to call "prepareResult", then "getResult". Now, I can think of well designed code that employs some of these features. Hadoop Mapper interface extends JobConfigurable and Closeable, but I see a big difference because it's a framework that uses user code implementing those interfaces, versus a service that could have multiple implementations. I suppose anything related to including a "close" method that must be called is justified, since there isn't any other reasonable way to do it. In some cases, like JDBC, this is a consequence of a leaky abstraction, but in the two pieces of code I'm thinking of, it's pretty clearly a consequence of programmers hastily adding an interface to a spaghetti code class to clean it up.
My questions are:
Does everyone agree this is a poorly designed interface?
Is this a described anti-pattern?
Does this kind of initialization ever belong in an interface?
Does this only seem wrong to me because I have a preference for functional style and immutability?
If this is common enough to deserve a name, I suggest the "Secret Handshake" anti-pattern for an interface that forces you to call multiple methods in a particular order when the interface isn't inherently stateful (like a Collection).
Yes, it's an anti-pattern: Sequential coupling.
I'd refactor into Options - passed to the factory, and Results, returned from an analyseText() method.
I'd expect to see the AnalyzerFactory get passed the necessary params and do the construction itself; otherwise, what exactly is it doing?
Not sure if it does have a name, but it seems like it should :)
Yes, occassionally it's convenient (and the right level of abstraction) to have setters in your interface and expect classes to call them. I'd suggest that doing so requires extensive documentation of that fact.
Not really, no. A preference for immutability is certainly a good thing, and setter/bean based design can be the "right" choice sometimes too, but your given example is taking it too far.
I'm not sure whether it's a described anti-pattern but I totally agree this is a poorly designed interface. It leaves too much opportunity for error and violates at least one key principle: make your API hard to misuse.
Besides misuse, this API can also lead to hard-to-debug errors if multiple threads make use of the same instance.
Joshua Bloch actually has an excellent presentation (36m16s and 40m30s) on API design and he addresses this as one of the characteristics of a poorly designed API.
I can't see anything bad in here. setText() prepares the stage; after that, you have one or more calls to getOccurances(). Since setText() is so expensive, I can't think of any other way to do this.
getOccurances(text, query) would fix the "secret handshake" at a tremendous performance cost. You could try to cache text in getOccurances() and only update your internal caches when the text changes but that starts to look more and more like sacrifice to some OO principle. If a rule doesn't make sense, then don't apply it. Software developers have a brain for a reason.
One possible solution - use Fluent chaning. That avoids a class containing methods that need to called in a certain order. It's a lot like the builder pattern which ensures you don't read objects that are still in the middle of being populated.