From 446a2b29ad7dec78eaeda9bbb9c7a273587e5e53 Mon Sep 17 00:00:00 2001 From: Isaac Good Date: Mon, 25 May 2026 15:34:35 -0700 Subject: [PATCH 1/2] Format all `instructions.append.md` to start with an H1 (required but ignored) and H2 --- .../anagram/.docs/instructions.append.md | 2 + .../connect/.docs/instructions.append.md | 12 +++-- .../gigasecond/.docs/instructions.append.md | 5 +- .../leap/.docs/instructions.append.md | 6 ++- .../lens-person/.docs/instructions.append.md | 7 ++- .../.docs/instructions.append.md | 46 ++++++++++--------- .../phone-number/.docs/instructions.append.md | 13 ++++-- .../robot-name/.docs/instructions.append.md | 8 +++- .../.docs/instructions.append.md | 9 +++- .../.docs/instructions.append.md | 8 +++- 10 files changed, 78 insertions(+), 38 deletions(-) diff --git a/exercises/practice/anagram/.docs/instructions.append.md b/exercises/practice/anagram/.docs/instructions.append.md index 2b17bb7a3..0f5c35b6a 100644 --- a/exercises/practice/anagram/.docs/instructions.append.md +++ b/exercises/practice/anagram/.docs/instructions.append.md @@ -1,3 +1,5 @@ # Instructions Append +## Implementation + You must return the anagrams in the same order as they are listed in the candidate words. diff --git a/exercises/practice/connect/.docs/instructions.append.md b/exercises/practice/connect/.docs/instructions.append.md index f9ccf2c63..e464ab224 100644 --- a/exercises/practice/connect/.docs/instructions.append.md +++ b/exercises/practice/connect/.docs/instructions.append.md @@ -1,6 +1,12 @@ -# Hints -You may notice that some test cases seem unfair. However, they may be legitimately so. For example, it is common to give young or beginner players an extra n pieces at fixed positions on the board, so mismatched piece counts can occur in an otherwise fully legal game. +# Instructions append -In any case, this exercise cares only about determining a winner for a game that can have a variety of parameters, like board length and extra pieces. It is not interested in any other state of the game, such as who moved where, when, or whose turn it is. +## Hints + +You may notice that some test cases seem unfair. +However, they may be legitimately so. +For example, it is common to give young or beginner players an extra n pieces at fixed positions on the board, so mismatched piece counts can occur in an otherwise fully legal game. + +In any case, this exercise cares only about determining a winner for a game that can have a variety of parameters, like board length and extra pieces. +It is not interested in any other state of the game, such as who moved where, when, or whose turn it is. So don't be puzzled by those seemingly unfair games. diff --git a/exercises/practice/gigasecond/.docs/instructions.append.md b/exercises/practice/gigasecond/.docs/instructions.append.md index 233d86700..d750270eb 100644 --- a/exercises/practice/gigasecond/.docs/instructions.append.md +++ b/exercises/practice/gigasecond/.docs/instructions.append.md @@ -1,2 +1,5 @@ -# Hints +# Instructions append + +## Hints + Note that `addGigaseconds` accepts two different types of input. diff --git a/exercises/practice/leap/.docs/instructions.append.md b/exercises/practice/leap/.docs/instructions.append.md index f7e0b9b21..68ef51b8d 100644 --- a/exercises/practice/leap/.docs/instructions.append.md +++ b/exercises/practice/leap/.docs/instructions.append.md @@ -1,4 +1,8 @@ # Hints + +## Implementation + Try to avoid code repetition, use private helper functions if you can. -And you might consider using a single `Boolean` expression instead of `if-else` for better readability. See [here](http://cs.wellesley.edu/~cs111/spring00/lectures/boolean-simplification.html) on how this could be done (the link is for Java, but of course the logic is valid for Scala, too). +And you might consider using a single `Boolean` expression instead of `if-else` for better readability. +See [here](http://cs.wellesley.edu/~cs111/spring00/lectures/boolean-simplification.html) on how this could be done (the link is for Java, but of course the logic is valid for Scala, too). diff --git a/exercises/practice/lens-person/.docs/instructions.append.md b/exercises/practice/lens-person/.docs/instructions.append.md index 527813db3..c13deb84c 100644 --- a/exercises/practice/lens-person/.docs/instructions.append.md +++ b/exercises/practice/lens-person/.docs/instructions.append.md @@ -1,2 +1,5 @@ -In Scala, a popular alternative for using Lens that is supported -by Exercism is [Monocle](https://www.optics.dev/Monocle/) \ No newline at end of file +# Instructions append + +## Implementation + +In Scala, a popular alternative for using Lens that is supported by Exercism is [Monocle](https://www.optics.dev/Monocle/) diff --git a/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md b/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md index 168898399..49cb70f82 100644 --- a/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md +++ b/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md @@ -1,26 +1,30 @@ -# Hints -According to [this terminology](http://chimera.labs.oreilly.com/books/1230000000929/ch01.html#sec_terminology) you should write a *parallel* and *deterministic* -program and (by all means!) let Scala deal with the *concurrency* aspect. -Or else your code could quickly get messy and error-prone with all kinds of nasty -concurrency bugs. In particular your program could become indeterministic -which spells in practice: very (in fact, VERY) hard to debug, test and reason about. - -Having said that it might be a good idea to first write a sequential solution (and -use the test suite to verify it). -Only then should you try to parallelize it while keeping the sequential and parallel -portions of your code as separate as possible. - -A first iteration could be using Scala's [parallel collections](http://docs.scala-lang.org/overviews/parallel-collections/overview.html). You might find -that this is almost too simple (especially if you have followed our advice and -already have a sequential solution). - -For the second iteration we recommend you try a solution with [scala.concurrent.Future](http://www.scala-lang.org/api/current/scala/concurrent/Future$.html). -You can consult [this tutorial](http://danielwestheide.com/blog/2013/01/09/the-neophytes-guide-to-scala-part-8-welcome-to-the-future.html) and [its sequel](http://danielwestheide.com/blog/2013/01/16/the-neophytes-guide-to-scala-part-9-promises-and-futures-in-practice.html) for some help. +# Instructions append + +## Hints + +According to [this terminology][terminology] you should write a *parallel* and *deterministic* program and (by all means!) let Scala deal with the *concurrency* aspect. +Or else your code could quickly get messy and error-prone with all kinds of nasty concurrency bugs. +In particular your program could become indeterministic which spells in practice: very (in fact, VERY) hard to debug, test and reason about. + +Having said that it might be a good idea to first write a sequential solution (and use the test suite to verify it). +Only then should you try to parallelize it while keeping the sequential and parallel portions of your code as separate as possible. + +A first iteration could be using Scala's [parallel collections]. +You might find that this is almost too simple (especially if you have followed our advice and already have a sequential solution). + +For the second iteration we recommend you try a solution with [`scala.concurrent.Future`][Future]. +You can consult [this tutorial][tutorial] and [its sequel][sequel] for some help. Make sure that you + - have only one single blocking call to wait for the result - that it is at the very end of your program, and - that it has a timeout. -`scala.concurrent.Future` is used in many libraries and the doctor's advice for -parallel and asynchronous programming in Scala. So it is essential for mastering -the language and it should become part of your Scala armory. +`scala.concurrent.Future` is used in many libraries and the doctor's advice for parallel and asynchronous programming in Scala. +So it is essential for mastering the language and it should become part of your Scala armory. + +[terminology]: http://chimera.labs.oreilly.com/books/1230000000929/ch01.html#sec_terminology +[parallel collections]: http://docs.scala-lang.org/overviews/parallel-collections/overview.html +[Future]: http://www.scala-lang.org/api/current/scala/concurrent/Future$.html +[tutorial]: http://danielwestheide.com/blog/2013/01/09/the-neophytes-guide-to-scala-part-8-welcome-to-the-future.html +[sequel]: http://danielwestheide.com/blog/2013/01/16/the-neophytes-guide-to-scala-part-9-promises-and-futures-in-practice.html diff --git a/exercises/practice/phone-number/.docs/instructions.append.md b/exercises/practice/phone-number/.docs/instructions.append.md index 497793a80..2ca7bdddd 100644 --- a/exercises/practice/phone-number/.docs/instructions.append.md +++ b/exercises/practice/phone-number/.docs/instructions.append.md @@ -1,9 +1,14 @@ -# Hints -For simplicity and readability: Consider using the Scala collection functions instead of Java's `String` methods. Remember that in Scala a `String` is implicitly also a `Seq[Char]`, so you can call them as easily as the `String` methods. +# Instructions append + +## Hints + +For simplicity and readability: Consider using the Scala collection functions instead of Java's `String` methods. +Remember that in Scala a `String` is implicitly also a `Seq[Char]`, so you can call them as easily as the `String` methods. Some examples: - `filter` instead of `replaceAll` - `take`, `takeRight`, `drop`, `head`, `tail` instead of `substring` -Another idea worth exploring might be to change the `String` into a `List[Char]` -and then use [pattern matching](http://alvinalexander.com/scala/how-to-use-lists-nil-cons-scala-match-case-expressions) with the `::` operator. +Another idea worth exploring might be to change the `String` into a `List[Char]` and then use [pattern matching] with the `::` operator. + +[pattern matching]: http://alvinalexander.com/scala/how-to-use-lists-nil-cons-scala-match-case-expressions diff --git a/exercises/practice/robot-name/.docs/instructions.append.md b/exercises/practice/robot-name/.docs/instructions.append.md index 3c5d479e2..b9ab4fbf5 100644 --- a/exercises/practice/robot-name/.docs/instructions.append.md +++ b/exercises/practice/robot-name/.docs/instructions.append.md @@ -1,5 +1,9 @@ -# Hints -Make sure your solution is general enough to be easily scalable for longer names containing more letters and digits. This usually makes for better code quality, too. +# Instructions append + +## Hints + +Make sure your solution is general enough to be easily scalable for longer names containing more letters and digits. +This usually makes for better code quality, too. Suggestion (this is not explicitly tested): To make sure you always have a unique name you could implement your own cache or use a `Stream` with its built-in cache. diff --git a/exercises/practice/roman-numerals/.docs/instructions.append.md b/exercises/practice/roman-numerals/.docs/instructions.append.md index 0f0db3086..4e54677d3 100644 --- a/exercises/practice/roman-numerals/.docs/instructions.append.md +++ b/exercises/practice/roman-numerals/.docs/instructions.append.md @@ -1,4 +1,7 @@ -# Hints +# Instructions append + +## Hints + For something a little different you might also try a solution with an `unfold` function. You are probably already familiar with `foldLeft/Right`: "map" a whole collection into something else (usually a non-collection). `unfoldLeft/Right` are the "inverse" operations: "map" something (usually a non-collection) into a collection. @@ -7,4 +10,6 @@ So `unfold`ing is a logical addition to and part of the FP standard repertoire. This exercise can be seen as a case for `unfold`ing: "map" an `Int` into a `String` (which is of course implicitly a `Seq[Char]`). Unfortunately `unfoldLeft/Right` is not included in Scala's collection library. -But you can take the implementation from [here](http://daily-scala.blogspot.de/2009/09/unfoldleft-and-right.html). +But you can take the implementation from [here][unfold]. + +[unfold]: http://daily-scala.blogspot.de/2009/09/unfoldleft-and-right.html diff --git a/exercises/practice/variable-length-quantity/.docs/instructions.append.md b/exercises/practice/variable-length-quantity/.docs/instructions.append.md index 34d77e366..7e2641e9a 100644 --- a/exercises/practice/variable-length-quantity/.docs/instructions.append.md +++ b/exercises/practice/variable-length-quantity/.docs/instructions.append.md @@ -1,2 +1,6 @@ -# Hints -Remember that in Scala there are two forms of the right shift operator. The `>>` operator preserves the sign, while `>>>` zeroes the leftmost bits. +# Instructions append + +## Hints + +Remember that in Scala there are two forms of the right shift operator. +The `>>` operator preserves the sign, while `>>>` zeroes the leftmost bits. From 3cc103414806572839d3f578260bee97508a0620 Mon Sep 17 00:00:00 2001 From: Isaac Good Date: Tue, 26 May 2026 22:17:13 -0700 Subject: [PATCH 2/2] Update the header to "Track specific instructions" --- exercises/practice/anagram/.docs/instructions.append.md | 2 +- exercises/practice/connect/.docs/instructions.append.md | 2 +- exercises/practice/gigasecond/.docs/instructions.append.md | 2 +- exercises/practice/leap/.docs/instructions.append.md | 2 +- exercises/practice/lens-person/.docs/instructions.append.md | 2 +- .../parallel-letter-frequency/.docs/instructions.append.md | 2 +- exercises/practice/phone-number/.docs/instructions.append.md | 2 +- exercises/practice/robot-name/.docs/instructions.append.md | 2 +- exercises/practice/roman-numerals/.docs/instructions.append.md | 2 +- .../variable-length-quantity/.docs/instructions.append.md | 2 +- 10 files changed, 10 insertions(+), 10 deletions(-) diff --git a/exercises/practice/anagram/.docs/instructions.append.md b/exercises/practice/anagram/.docs/instructions.append.md index 0f5c35b6a..b11c894ef 100644 --- a/exercises/practice/anagram/.docs/instructions.append.md +++ b/exercises/practice/anagram/.docs/instructions.append.md @@ -1,5 +1,5 @@ # Instructions Append -## Implementation +## Track specific instructions You must return the anagrams in the same order as they are listed in the candidate words. diff --git a/exercises/practice/connect/.docs/instructions.append.md b/exercises/practice/connect/.docs/instructions.append.md index e464ab224..bde792486 100644 --- a/exercises/practice/connect/.docs/instructions.append.md +++ b/exercises/practice/connect/.docs/instructions.append.md @@ -1,6 +1,6 @@ # Instructions append -## Hints +## Track specific instructions You may notice that some test cases seem unfair. However, they may be legitimately so. diff --git a/exercises/practice/gigasecond/.docs/instructions.append.md b/exercises/practice/gigasecond/.docs/instructions.append.md index d750270eb..fe00478f2 100644 --- a/exercises/practice/gigasecond/.docs/instructions.append.md +++ b/exercises/practice/gigasecond/.docs/instructions.append.md @@ -1,5 +1,5 @@ # Instructions append -## Hints +## Track specific instructions Note that `addGigaseconds` accepts two different types of input. diff --git a/exercises/practice/leap/.docs/instructions.append.md b/exercises/practice/leap/.docs/instructions.append.md index 68ef51b8d..3562a378e 100644 --- a/exercises/practice/leap/.docs/instructions.append.md +++ b/exercises/practice/leap/.docs/instructions.append.md @@ -1,6 +1,6 @@ # Hints -## Implementation +## Track specific instructions Try to avoid code repetition, use private helper functions if you can. diff --git a/exercises/practice/lens-person/.docs/instructions.append.md b/exercises/practice/lens-person/.docs/instructions.append.md index c13deb84c..877196317 100644 --- a/exercises/practice/lens-person/.docs/instructions.append.md +++ b/exercises/practice/lens-person/.docs/instructions.append.md @@ -1,5 +1,5 @@ # Instructions append -## Implementation +## Track specific instructions In Scala, a popular alternative for using Lens that is supported by Exercism is [Monocle](https://www.optics.dev/Monocle/) diff --git a/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md b/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md index 49cb70f82..47dbae5e5 100644 --- a/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md +++ b/exercises/practice/parallel-letter-frequency/.docs/instructions.append.md @@ -1,6 +1,6 @@ # Instructions append -## Hints +## Track specific instructions According to [this terminology][terminology] you should write a *parallel* and *deterministic* program and (by all means!) let Scala deal with the *concurrency* aspect. Or else your code could quickly get messy and error-prone with all kinds of nasty concurrency bugs. diff --git a/exercises/practice/phone-number/.docs/instructions.append.md b/exercises/practice/phone-number/.docs/instructions.append.md index 2ca7bdddd..29acf8dbd 100644 --- a/exercises/practice/phone-number/.docs/instructions.append.md +++ b/exercises/practice/phone-number/.docs/instructions.append.md @@ -1,6 +1,6 @@ # Instructions append -## Hints +## Track specific instructions For simplicity and readability: Consider using the Scala collection functions instead of Java's `String` methods. Remember that in Scala a `String` is implicitly also a `Seq[Char]`, so you can call them as easily as the `String` methods. diff --git a/exercises/practice/robot-name/.docs/instructions.append.md b/exercises/practice/robot-name/.docs/instructions.append.md index b9ab4fbf5..d3905c276 100644 --- a/exercises/practice/robot-name/.docs/instructions.append.md +++ b/exercises/practice/robot-name/.docs/instructions.append.md @@ -1,6 +1,6 @@ # Instructions append -## Hints +## Track specific instructions Make sure your solution is general enough to be easily scalable for longer names containing more letters and digits. This usually makes for better code quality, too. diff --git a/exercises/practice/roman-numerals/.docs/instructions.append.md b/exercises/practice/roman-numerals/.docs/instructions.append.md index 4e54677d3..19c6d4536 100644 --- a/exercises/practice/roman-numerals/.docs/instructions.append.md +++ b/exercises/practice/roman-numerals/.docs/instructions.append.md @@ -1,6 +1,6 @@ # Instructions append -## Hints +## Track specific instructions For something a little different you might also try a solution with an `unfold` function. You are probably already familiar with `foldLeft/Right`: "map" a whole collection into something else (usually a non-collection). diff --git a/exercises/practice/variable-length-quantity/.docs/instructions.append.md b/exercises/practice/variable-length-quantity/.docs/instructions.append.md index 7e2641e9a..07f08c934 100644 --- a/exercises/practice/variable-length-quantity/.docs/instructions.append.md +++ b/exercises/practice/variable-length-quantity/.docs/instructions.append.md @@ -1,6 +1,6 @@ # Instructions append -## Hints +## Track specific instructions Remember that in Scala there are two forms of the right shift operator. The `>>` operator preserves the sign, while `>>>` zeroes the leftmost bits.