Problem-specifications: Shall we continue to explicitly specify that some exercises are refactoring exercises?

[petertseng]

We currently have three refactoring exercises:

• https://github.com/exercism/problem-specifications/blob/master/exercises/ledger/description.md (added in https://github.com/exercism/problem-specifications/pull/58)
• https://github.com/exercism/problem-specifications/blob/master/exercises/tree-building/description.md (added in https://github.com/exercism/problem-specifications/pull/60)
• https://github.com/exercism/problem-specifications/blob/master/exercises/markdown/description.md (added in https://github.com/exercism/problem-specifications/pull/262)

In https://github.com/exercism/discussions/issues/24 we affirm that we would indeed like to have refactoring exercises.

In the description of each exercise, we explicitly write the word "Refactor" to tell us that this is indeed a refactoring exercise.

I'd like to confirm real quick that we do want to continue the practice of explicitly specifying these exercises as refactoring, as opposed to a possible alternative of "say nothing; let tracks individually decide which exercises are refactoring exercises and which are not". I'm doing this because by challenging the assumption we will either find our strong reasons to support the assumption (and then we can refer to these reasons in the future!), or we will realise the need for a change.

If we let each track individually decide whether a given exercise is a refactoring exercise or not, that would be a good change because:

• It gives track maintainers more flexibility to shape the curriculum in a way that makes sense for the language (if having the exercise is educational but for some reason having it as a refactoring exercise would be less educational)
• Your reason here!

If we explicitly specify in the description that some exercises are refactoring exercises, that would continue to be good because:

• It's a more consistent experience for students if an exercise that is a refactoring exercise in one track is also a refactoring exercise in another; that means it's easier to set expectations
• Your reason here!

[nathanielknight]

I like having Refactoring exercises called out. It goes well with the messaging around reading code and getting feedback: it's a big part of programming that some practice curricula don't pay much attention to. As a "student", it gives me faith that the curriculum understands what my job is and cares about helping me get better at all of it, not just the funnest parts.

[cmccandless]

It's a more consistent experience for students if an exercise that is a refactoring exercise in one track is also a refactoring exercise in another; that means it's easier to set expectations

Consistency between tracks is something that comes up often in discussions around here, and the general consensus most of the time is that tracks should be as consistent with each other as possible (i.e. only language-specific features should be different).

[petertseng]

Thanks for the input.

I would like to close the issue to prevent it from taking up space in the open issues list. It would be useful to keep it open longer if there were proponents of both sides.

Even though it is closed, feel free to comment if you would like to provide an additional viewpoint in the future.

[sshine]

I would like to open this discussion again with an argument to make "refactoring" a tag rather than a property in problem-specifications. I think track consistency is the driving argument for a lot of decisions made, and I will not argue against it.

I will argue that refactoring is a track-dependent property: It is mainly a question of how elaborate the handed out stub file is. Stubs are very track-dependent: Some tracks (OCaml) don't have stubs, and others (Haskell) has a stub for every part.

This is partly a consequence of how dynamic the languages and test frameworks are (can we test that something is missing, or will this simply result in a nonsensical compilation error), and partly a consequence of different opinions among track maintainers: E.g. @kotp and I discussed in private the lack of stubs on the Perl track as a method to teach module creation; this depends highly on the order of the exercises, the length of the core track, and the pace at which concepts are introduced.

Just like one exercise can have the (track-specific) tag "either" in one track (meaning it deals with error-aware return types), and not in another track, the nature of an exercise may necessitate error handling in one language and not in another, in a similar fashion, some exercises are better suited as refactoring exercises in some languages / tracks.

For example, in an effort to popularize the Data.Text library in Haskell, exercism/haskell#780 deals with the learning curve of going from the default String type to the more optimal Text type; we'd like a refactoring exercise that deals with strings about halfway through the core track, but none of the three existing refactoring exercises apply. (Markdown does apply, but it's too difficult at this stage.)

We could create an exercise just for this purpose, but that will also lower track consistency (either because the exercise is track-specific, or because it won't be adopted by many tracks with similar needs).

What I would much rather do is pick one of the many string-based exercises that have gone through design, implementation and maintenance, and just write a slightly larger, uglier stub file, and add the tag "refactoring". Should the philosophy of the core track change at a later time, it could be changed away from being a refactoring exercise very easily as well.

[petertseng]

Policy:

Imagine for a moment that we do not reach agreement here on the idea that refactoring should be a track-specific decision.

However, there are currently no enforcement mechanisms.

So, if a track's maintainers decide "well, this is what's best for our track, agree to disagree", it doesn't seem like there's a whole lot that other tracks' maintainers can do about it.

For this reason, gaining consensus on policy would only be important to me to the extent that implementation details would hinder me in doing what I want to do.

Implementation:

As we see via git grep -i refactor, three exercises contain "refactor" in the description: ledger, markdown, tree-building.

If a track wishes to designate another exercise, not among these three, as a refactoring exercise, what additional steps must it take?

• Probably add a .meta/hints.md so that students get instructions commensurate with it being a refactoring exercise. We see that it is easy to purely add to a README.
• Any other steps that I missed

If a track wishes to use one of the aforementioned three exercises, but not have it be a refactoring exercise, what additional steps must it take?

• Presumably add a .meta/description.md so that students get instructions suitable for it not being a refactoring exercise.
  
  
  
  • We can't use .meta/hints.md here because the problem-specifications description.md already contains the word "Refactor". It would seem internally inconsistent if a later section of the README said "haha disregard that, it's not a refactoring exercise after all!".
  
  
  • We see that it is not easy to remove or change portions of the common READMEs. I may have thought of some solution involving .patch files, but even that is implementable on a track-local basis.
  
  
• Any other steps that I missed

I imagine that in either case, a track that makes either of these decisions is still able to use the canonical-data.json for the tests, so we still have the power to ensure good test coverage across all tracks.

So that gives an idea of the costs of deviation, and therefore the desirability of obtaining consensus.