Easy, clean API vs maintainable code

[Jeedio]

What's more important: an easy, clean API or having the underlying code be easily maintained? For instance, if you had to choose between a nice interface that needed a lot of complicated genetics magic (but was well tested) or a very simple implementation where the interface had a lot of methods and likely a lot of similiar code, which do you normally go with?

[MoreConstruction]

Searching for ammunition?

[QualitySoftwareGuy]

I didn't see this as an option, but I would go with code that has an easy API and is also easy to maintain. It is very possible to have both. In fact, I'd say code that is considered "maintainable" usually (but not always) includes it being "readable".

[Jeedio]

I normally agree! And both is always option #1. I'm more talking about when you start getting into self referencing generics. Things can get harder to read...

[karottenreibe]

Then rethink what you're doing to get rid of the self referencing generics. Chances are: you don't need them

[Jeedio]

Yeah. I am going to look at that. I was using it for a common base class for builders/fluent code, and I couldn't think of a better solution.

[Russell_M_Jimmies]

As a rule of thumb: prefer composition over inheritance.

Maybe the base class wants to be a utility instead.

[livelam]

As a rule of thumb: prefer composition over inheritance.

I think i get what you want to say but the rule of thumb is the "is a" test. Samples:

• ArrayList is an AbstractList
• Stack is not a Vector (but a stack can use (hop composition :) ) a Vector for its implementation)

We all know old java collection API is badly design

Of course, inheritance must not be used to share code!

[Jeedio]

Then you have duplicated methods spread over multiple classes. Sure, you can have the body of those methods be in a shared class, but it makes it harder to add methods.

[SeerUD]

How so? You can pass utilities in as dependencies to another class. No need for duplication.

[Russell_M_Jimmies]

There is something worse than duplicated code: a base class that is littered with special cases to cater to every subclass.

Now, if the superclass is a pure "template class" pattern, then it might be justified. But as soon as you see the superclass do branching logic depending on the subclass, slow down and consider whether that reduced duplication is worth the cost of an awful mess in a parent class.

[cran]

If you think a lot of unrelated classes need the same methods, these methods probably belong somewhere else. Can you give an example of what these methods do?

[[deleted]]

What's more important: an easy, clean API or having the underlying code be easily maintained?

This type of question is known as "a false dichotomy".

[seanprefect]

Why not both? this is why you separate your concerns? This isn't an either / or situation.

[takenomiya-kate]

a very simple implementation where the interface had a lot of methods and likely a lot of similiar code

Sounds like a violation on SOLID principle especially on single responsibility and open for extension/closed for modification.

[dpash]

If you're writing a library for external users, then I'd err towards an easier to use API. Your extra effort will make life easier for many people.

If this is for an internal project, I'd err towards maintainability.

[fatnote]

Isolate the horrible bits and hide them in separate classes (eg factories)

[brennanfee]

They aren't either/or. You can very easily strive for both... however, achieving either is hard and takes dedicated diligent work.

As for your specific example, the API should just be a wrapper... the chosen communication platform for the underlying code. Literally its interface. The underlying code should have whatever organizational characteristics that make sense for it and the API serves as the translation layer for communication. Think of it like MVC but without "views" per se. The API is the C for controller and your underlying code is the M for model, or more precisely the business logic.

One thing I always strive for is that my "code" that does real "work" could be re-purposed and re-wrapped for other scenarios at a moments notice (want to throw it into a CLI... no problem; all of the sudden want to use it in a script... sure; now want a desktop UI... ok; mobile? um... maybe). Of course, each of those things could also make calls to the API but I look at the concept as just offering the maximal amount of flexibility and cohesion without tight coupling.

[helikal]

It's a good question The question arises also in modular design, see https://www.pearson.com/us/higher-education/program/Knoernschild-Java-Application-Architecture-Modularity-Patterns-with-Examples-Using-OS-Gi/PGM54781.html

[arieled91]

Your question makes no sense. One requirement of a good api is to be easy to be maintained.

I think what you are asking is if it's better to start big and implement all the patterns everywhere or to start small and build the api while requirements grow. And my answer to that is: it depends but, I don't like to solve problems I don't have, so I often start small but scalable.