[policy] Prefer object-based APIs (instance methods) over class-based (static methods)

[stkent]

Some exercise test suites force the use of static methods exclusively (e.g. nth-prime); others force the use of objects (e.g. anagram). Is there a preference for one paradigm vs the other? Having users switch back and forth between the two while working through exercises seems unnecessarily confusing.

[jtigger]

This topic (AFAIK) has not been discussed in the broad scope you're framing, @stkent. I see one "discussion" in #90.

tl;dr: most (all?) of these exercises should be implemented in the form of instance methods since they contain "domain logic" and we (Exercism) want to encourage exemplary software.

An argument:

1. A programmer participating in Exercism should be exposed to our best understanding of how to design "good" software.
2. "Good" software design maximizes the profit of a product over its lifetime (i.e. minimize maintenance and development costs while maximizing value delivered through its use).
3. As a product increases in complexity, so does the risk of maintenance costs:
   • as complexity increases, so does the risk of defects;
   • as complexity increases, so does the difficulty in isolating defects;
   • the effort required to isolate and properly address defects is a maintenance cost.
4. Such risk can be materially mitigated by co-developing a testing system alongside the product such that this testing system:
   • exercises the product in ways that is likely to expose defects in essential logic (colloquially, "domain logic");
   • is used frequently so as to expose such defects as soon as possible (read: executes expeditiously);
   • is maintained along with the product.
5. For such a testing system to be feasible, the product itself must be testable:
   • individual components of the product should be easy to isolate so as to exercise them sufficiently to gain confidence that they each behave as desired in a given context.
6. To achieve that isolation, the product's components must support at least two flavors of its dependencies: at least one production implementation and one test double implementation.
7. In Java, the least surprising way to provide two implementations for the same behavior is to use virtual functions.
8. In Java, instance methods are, by default, virtual functions; static methods are not.

[jtigger]

There are a number of maintainers here. @exercism/java, care to chime in?

@stkent, what's your point of view?

[matthewmorgan]

@jtigger @stkent i agree with John in principle. I do think it's useful if we can to provide some exposure to static methods as a feature of the language.

In the ecmascript track we had a similar issue with the use of class based solutions versus functional or object literal solutions. We ended up setting an "on boarding" pattern of requiring classes for the first dozen exercises, then mixed it up after that.

Having said all that, I think the goal of promoting good practices should take priority over exploring all language features.

[stkent]

@jtigger that's a great breakdown! The tension I see revolves around this part:

As a product increases in complexity, so does the risk of maintenance costs [...]

Since Exercism exercises are standalone we know this increase in complexity will not occur. Optimizing architecture for non-existing scaling therefore smells a bit of YAGNI. On balance, though, I think this concern is much less important than introducing language best practices, so I lean towards moving towards object-based implementations for all exercises (with the possible exception of Hello World).

[jtigger]

I totally get that, @stkent.

Many years back, I spent some time with a master photographer who shared with me this bit of advice should I ever get started in photography: that one should start with simple subjects on medium format film (much larger than 35mm) so that your errors stick out like sore thumbs.

I take this perspective on Exercism exercises: while in their expression, they are small in scope, this is a space to also practice what it looks/feels like to make choices that support future needs. It's subtly not YAGNI. You need to define these methods, the question is in what form?

In fact, I'd love to add a whole 'nother dimension to these exercises by providing a choose your own adventure style of subsequent paths, each designed to likely require a refactor to accommodate. In this way, practitioners would be encouraged to explore the space more and evaluate the consequences of their initial design choices (or lack thereof) and hopefully elicit related discussion on the website (read: surfacing additional valuable conversations about the design of code — the heart of the value of Exercism).

I do understand — we're not there yet. :)

[jtigger]

@matthewmorgan said, above:

Having said all that, I think the goal of promoting good practices should take priority over exploring all language features.

Agreed. While we don't have to hit all of the language features, koan-style, to the extent we don't hit the major ones today it's a disservice to the practitioner. This is a thing I'd like to keep in mind as we tackle #142.

[stkent]

In fact, I'd love to add a whole 'nother dimension to these exercises by providing a choose your own adventure style of subsequent paths, each designed to likely require a refactor to accommodate. In this way, practitioners would be encouraged to explore the space more and evaluate the consequences of their initial design choices (or lack thereof) and hopefully elicit related discussion on the website (read: surfacing additional valuable conversations about the design of code — the heart of the value of Exercism).

Man, that sounds great! Looking forward to it :)

The points raised here are all excellent, though it seems like this and other issues (e.g. #178) would be most efficiently tackled post-#142. I guess that makes #142 a priority right now?

[jtigger]

Why, yes... yes it is! It's the next "story" we're planning on tackling (see the xJava Track Maintenance backlog).

[stkent]

I'll leave this open so we can remember to circle back after #142.

[stkent]

@jtigger I saw you apply the policy label elsewhere in the issues list; would this be a good candidate for that same label? It is a decision that needs to be kept in mind over time (as we add new exercises that alter ordering). Just a thought.

[jtigger]

That's perfect, @stkent... it's the exact intent of the label — exercism/discussions#96. When you see things like this, please, you are fully "blessed" to take action!

[jtigger]

Renamed to clarify the decision within this discussion for ease-of-use.

[jtigger]

A "policy" is not a decision set-in-stone. It's a direction chosen at a point in time with the information/thinking on-hand. All decisions should be challenged.

To make a meaningful contribution, please include a new perspective and argue how it mixes in the values expressed and changes the decision.

[jtigger]

With the issues created, above, I believe that we've identified all of the exercises that need adjustments.

[stkent]

We should add this to the POLICIES doc and then close out this issue.

[FridaTveit]

There is already a section about this in the POLICIES doc. So we can proabaly close this issue unless you think that section should be expanded @stkent?

[stkent]

Good spot, I missed that! I think this is safe to close now, as it can be found via the reference in the POLICIES doc.