When designing an API for, say, a game. Would it be better to keep the data structures private, or would would returning the structures to the developers/who ever is using the API considered good design? So here’s an example.
Assume I have a chess board game API. Which of the following two examples would be considered “better”? Note that for the purpose of this question, I am assuming that the chess board size can vary and is controlled by the developer.
public void createboard(ChessBoard board);
public void move(Player playerNumber, Move move);
or
public void createboard(int x, int y);
public void move(Player playerNumber, int from[], int to[]);
I understand that there may be no better answer and it’s just a matter of design decision. I am just trying to see what other people think, or if there are any useful tips that anyone has.
Basically, I am assuming that the game contains an object called ChessBoard which contains a 2D array for the actual board.
The first example requires the developer to create the object and pass it and requires the developer to actually know what the underlying data structure is.
The second however, would require the developer to only pass in numbers. This would ask the developers using this to maintain their own data structures.
Which approach would you consider better design? Any tips?
When you’re exposing APIs the more of the internal implementation you keep hidden the better. Otherwise you’re potentially limiting yourself in the future with regards to further enhancements/changes as you’ll not want to break binary compatibility with developers using a previous revision of your API. (In ‘real-world’ cases there may be written agreements between client and customer regarding APIs saying they cannot be broken without explicit permission from the customer).
You should aim for allowing configuration through APIs yet not locking yourself internally to any particular implementation. It’s harder than it sounds and the language used is also a factor.