This post originated from an RSS feed registered with Java Buzz
by Ben Hosking.
Original Post: How to Design a Good API
Feed Title: A Funny Java Flavoured Look at the World
Feed URL: http://businesslogs.com/WebLog/RSS.xml
Feed Description: The blog looks at using Java and programming in general as it pops up in life as a Java programmer. It will have links to interesting Java articles and resources. It will also have a lot of SCJP Java 1.5 information and links as I am currently studying
I was reading this presentation on the Design of API's by Joshua Bloch it talk's about how to design a good api but more importantly the reasons why doing certain things results in a good design.
He makes a point where he says good code is modular and each module has an API. He also says useful modules tend to get reused. I don't really design any public API's but recently I have been thinking about the code I write as a public API. I think you have think about code as self contained public API that other people will use. I think if you program classes and packages like this then you will create classes that are reusable. I think it's quite staggering the amount of code that isn't reused in other parts of the software or in other projects. One of the reasons why classes and packages can't be reused because it isn't designed very well and isn't designed with a good API.
The presentation makes some very good points in the presentation and I will mentions the points I particularly found useful but I would definitely recommend looking at the presentation and it doesn't take long because it's a presentation and not an article.
Naming Names of classes and methods should be largely self explanatory, if they are hard to name then this is usually a sign that the class or method is doing to much. You should also name methods and classes in a consistent way and if possible use stick to naming standards.
Minimize Mutability The presentation states
"Classes should be immutable unless there?s a good reason to do otherwise"
I have recently been trying to make more classes immutable because it allows you to not worry about the variables changing value and worry about validating the possible changing of values and writing code to react to these changes. When you think about this point in more detail the more I found it makes sense. In some ways I think we start programming in the wrong way, everyone makes classes mutable by default and we are encourage to put getters and setters everywhere so we are encapsulating the variable. I think that we should start with making things immutable and then only if we decide we want people to change a variable then add a setter. When designing a class if you think about the mutability of a class then I think you will understand the purpose of the class more. Immutable classes are also thread safe and very easy to reuse.
Access Similar to the previous point really but the presentation recommends
"Minimise the accessibility of everything"
In the same way you want to create things immutable and not have setters methods for internal variables if you decide they shouldn't change. You should also try and hide the variables and methods as much as you can. This simplifies the use of your class and removes the possibility of bugs because it will mean users can't change the internal variables which might break the code in some way.
The presentation also gives this piece of advice
"if in doubt leave it out. You should make API's as small as possible"
I am often guilty of adding in functionality that I think might be useful or maybe useful in the future. Why? Then when I am writing a test for the function which I know probably isn't going to be used for the current problem, I think why have I put this method in. This is where this piece of advice is really useful, just leave it out and do as little as possible and don't waste your time writing code that you aren't going to use.
Overloading
" Avoid ambiguous overloadings _ Multiple overloadings applicable to same actuals _ Conservative: no two with same number of args ? Just because you can doesn't mean you should _ Often better to use a different name"
The quote's above I felt to be very useful because this is another area where I often am guilty of providing overloaded functions allowing for different variables. This is classic area where I should stop wasting my time writing this functions, do my fellow programmers really need so many overloaded functions to do the same thing. Probably not and if you find there is a real need for it you can add it in and it won't break the code that is using it.
Parameter Ordering Presentation recommends you
"Use Consistent Parameter Ordering Across Methods"
This is an excellent point because it will mean that people using your methods will get use to the same system or order. You are creating a standard. If you imagine overloaded functions then you can really see the value of this idea because using each of the overloaded functions can be used in a similar way.
The last interesting point is
"Avoid Return Values that Demand Exceptional Processing"
He uses the example that if a method returns a collection, you should return a collection with nothing in rather than a null which when the user checked the values in the collection it would error with a null exception. If you returned a collection with nothing in then it would look through it and find there is nothing in. It's pretty obvious that this piece of advice is going reduce the number of errors generated from using the class.
I found the presentation really useful and although the comments are probably obvious to a lot of people, there were some things I hadn't really thought about and hope to bring into my developer.
Previous Topic
