From 356b6067f7bcb51bfe686caf24a5d04c0df724e9 Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Wed, 22 Jan 2025 18:31:09 -0500 Subject: [PATCH 01/12] Adding a "Test-Driven Development" document --- using/config.json | 7 +++ using/faqs.md | 48 +++++++++++---------- using/solving-exercises/tdd.md | 78 ++++++++++++++++++++++++++++++++++ 3 files changed, 111 insertions(+), 22 deletions(-) create mode 100644 using/solving-exercises/tdd.md diff --git a/using/config.json b/using/config.json index b6085c26..18b9e3c4 100644 --- a/using/config.json +++ b/using/config.json @@ -63,6 +63,13 @@ "title": "Solving exercises", "blurb": "Learn how to solve exercises on Exercism" }, + { + "uuid": "d78582b0-d90a-45a7-a1b4-2e87dac645b1", + "slug": "solving-exercises/tdd", + "path": "using/solving-exercises/tdd.md", + "title": "What is Test-Driven Development?", + "blurb": "Use the TDD methodology and the given test suite to solve exercises" + }, { "uuid": "7b753e2a-bd68-4d68-bdd8-c356de4342b6", "slug": "solving-exercises/working-locally", diff --git a/using/faqs.md b/using/faqs.md index 76497e12..df2441b6 100644 --- a/using/faqs.md +++ b/using/faqs.md @@ -30,26 +30,31 @@ To learn more about what it means for the devil to be in the details, check out ## The Basics -## I'm lost. Where do I go? +### I'm lost. Where do I go? You're in luck. Here's a [step-by-step guide][getting-started] to get you started. If something is still unclear for you or not working then it might be the same for others so we'd appreciate you [letting us know on the forum][forum]. -## I get the error "Sorry, we could not authenticate you from GitHub" when trying to log in. What should I do? +### I get the error "Sorry, we could not authenticate you from GitHub" when trying to log in. What should I do? This means that GitHub isn't willing to verify who you are. That can be because you chose not to give permission or it might be because your GitHub account is not properly configured. A common problem is that you haven't verified your email address on GitHub. You can check that in your [GitHub email settings][email-settings]. -## How do I delete my account? +### How do I delete my account? You can delete your account by following the link at the bottom of your [settings page][settings]. If your issue is with emails and notifications you can adjust that in [your personal preferences][personal-settings]. -## How do I unlock exercises? +### What am I supposed to do to solve an exercise? + +When you start working on an exercise, you will have a "stub solution" that you need to complete, and you will have a complete test suite that represents the requirements your solution must satisfy. +This development methodology is a form of [Test-Driven Development][tdd]. + +### How do I unlock exercises? By default, tracks with Learning Exercises require you to solve Learning Exercises to unlock other exercises (each should take around 5 minutes to solve if you are fluent in a language). This is called [Learning Mode][learning-mode]. @@ -57,7 +62,7 @@ This is called [Learning Mode][learning-mode]. While we recommend using Learning Mode to progress through a track, you could [switch to Practice Mode][switching-modes] to unlock all exercises. For more information, see [unlocking exercises][unlocking-exercises]. -## Why have my unlocked exercises in the old site become locked? +### Why have my unlocked exercises in the old site become locked? By default, tracks with Learning Exercises require you to solve Learning Exercises to unlock other exercises (each should take around 5 minutes to solve if you are fluent in a language). This is called [Learning Mode][learning-mode]. @@ -70,7 +75,7 @@ For more information, see [unlocking exercises][unlocking-exercises]. ## Exercism Command-line Client -## I can't submit! What should I do? +### I can't submit! What should I do? The new site has a brand new command-line client, and also needs some extra metadata for your exercise. Read about how to [upgrade your command-line client and migrate your solutions for the new site][upgrade-cli]. @@ -78,16 +83,16 @@ Read about how to [upgrade your command-line client and migrate your solutions f If that doesn't help, or you didn't use the old version of the command-line client, please read through the [command-line client Walkthrough][cli-walkthrough]. If that doesn't help either, [please post on the forum][forum] and we will help you get it sorted out. -## How do I check the version of my command-line client? +### How do I check the version of my command-line client? The version command `exercism version` outputs the running version of the Exercism command-line client. By running the version command with the latest flag `exercism version --latest` you can check if there is a newer version available. -## How do I upgrade to the latest version of the command-line client? +### How do I upgrade to the latest version of the command-line client? The command `exercism upgrade` will upgrade to the latest available version of the command-line client if one is available. -## I get permission denied errors when upgrading! What should I do? +### I get permission denied errors when upgrading! What should I do? If you are receiving permission denied errors when trying to upgrade the command-line client, chances are the binary was installed via a system package manager (e.g Homebrew) or has been installed into a directory that you no longer have write access to. @@ -97,36 +102,36 @@ If your command-line client was installed manually, please check the path of the If so, use the tools provided by your system to change the permissions of the directory to grant write access to your user and trying upgrading again. If you are not sure if you created the directory, or the returned path is a system path, please use your system tools to uninstall the command-line client and reinstall using the [interactive walkthrough][interactive-walkthrough]. -## I get the "16-bit MS-DOS Subsystem" error dialog after upgrading on Windows. What should I do? +### I get the "16-bit MS-DOS Subsystem" error dialog after upgrading on Windows. What should I do? Prior to version 3.0.5 of the Exercism command-line client, there was a bug in the upgrade command that would replace the command-line client binary file with a single text file causing the "16-bit MS-DOS Subsystem" error. To resolve this issue remove the corrupt binary and reinstall the command-line client using the [interactive walkthrough][interactive-walkthrough]. ## Mentored Mode -## My queue hasn't updated in a while - is there something wrong? +### My queue hasn't updated in a while - is there something wrong? While wait times can be longer than normal for a number of reasons (number of mentors, time of year), it can also appear that the queue is not updating. This is not unusual and you should see movement fairly soon. If you your wait is far longer than the average, refer to [Opening an Issue][opening-an-issue] below. -## How many mentors does my track have? I only see a handful on the website. +### How many mentors does my track have? I only see a handful on the website. The website only shows mentors who have provided bio information for the website, not the actual number of mentors who are actively reviewing solutions. Rest assured, there are mentors working through their queues so hang in there! -## I submitted the wrong solution / file. What can I do? +### I submitted the wrong solution / file. What can I do? On the exercise page in question, navigate to "Your Iterations". If the unwanted iteration is folded, click the circled arrow. In the "dots" menu, select "Delete iteration". -## How can I report abuse or examples of bad mentoring? +### How can I report abuse or examples of bad mentoring? Please check our [Code of Conduct][coc] for more information about our expectations of conduct. If you would like to report something, please reach out to us at [abuse@exercism.org][mail-abuse] and we will try to fix or resolve the issue respecting both you and your privacy. -## Why can't I give feedback on representations? +### Why can't I give feedback on representations? To give feedback on representations for a track, you need to pass the following three criteria: @@ -136,24 +141,24 @@ To give feedback on representations for a track, you need to pass the following ## Improving Exercism -## This is great! How do I get involved? +### This is great! How do I get involved? There are a few different ways - becoming a mentor, managing a language track or reporting (or addressing!) issues on GitHub. You can see more on the [How to Contribute page][contribute]. -## How do new language tracks get added to the site? +### How do new language tracks get added to the site? A new language track gets created when a member of the community takes the lead on it and becomes a maintainer of the track. If you'd like to get involved in helping set one up, there are [instructions here][new-language-request]. -## Telling us when something is wrong +### Telling us when something is wrong If you find something that's wrong, please let us know by creating a thread on [the forum][forum]. Before creating a thread, be sure to check for existing discussions. Try a few different keywords. -## What if my issue is not listed here or on the forum? +### What if my issue is not listed here or on the forum? If your problem hasn't been resolved or reported, then create a new [forum post][forum]. @@ -164,7 +169,7 @@ Make sure to include the following information: 1. Instructions on how to reproduce the issue 1. If applicable, reference to any related issue using its issue number (formatted like #1203) -## What if there is an issue with language on the website? +### What if there is an issue with language on the website? If your issue pertains to an exercise in your language track, then please find the correct language track [from this list][from-this-list] and submit an issue there. Please specify if the issue is with the instructions or something language specific, using the template below. @@ -190,7 +195,6 @@ If you have spotted a typo or if you have a suggestion for clearer language or i [kytrinyx]: https://exercism.github.io/kytrinyx/ [languages]: https://github.com/search?q=topic%3Aexercism-track+org%3Aexercism&type=Repositories [learning-mode]: /docs/building/product/unlocking-exercises#h-learning-mode-vs-practice-mode - [mail-abuse]: mailto:abuse@exercism.org?subject=%5BCoC%5D] [forum]: https://forum.exercism.org/ [new-language-request]: https://github.com/exercism/generic-track/blob/main/README.md @@ -202,4 +206,4 @@ If you have spotted a typo or if you have a suggestion for clearer language or i [switching-modes]: /docs/building/product/unlocking-exercises#h-switching-modes [unlocking-exercises]: /docs/building/product/unlocking-exercises [upgrade-cli]: https://github.com/exercism/website-copy/blob/main/pages/cli_v1_to_v2.md -[website-copy]: https://github.com/exercism/website-copy/issues +[tdd]: https://exercism.org/docs/using/solving-exercises/tdd diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md new file mode 100644 index 00000000..d38ff451 --- /dev/null +++ b/using/solving-exercises/tdd.md @@ -0,0 +1,78 @@ +# Test-Driven Development (TDD) + +Test-Driven Development (sometimes called Test-First Development or Test-Driven Design) is the practice of writing the unit tests first, before you write a single line of implementation code. + +## On Exercism, the tests _are_ the requirements! + +Each exercise you work on will have some instructions describing in general terms what you need to do. +By design, these instructions do not account for programming-language-specific implementation details because they are shared by all of Exercism’s 70+ language tracks. +Some language tracks will append more specific details for you, but not all of them do. + +When you start working on an exercise, give the instructions a careful read. +They will give you a broad overview of how you go about implementing a solution. +But you will have to read the _tests_ to understand the full and exact requirements: + +- Must the result be a particular kind of data structure? +- Must the result be sorted in some order? +- How are you expected to handle exceptions? And so on. + +You have solved an exercise when all the provided tests run and pass. +In other words, your solution is not just an interpretation the instructions that "looks right", your solution is a program that _satisfies the given tests_. +**The tests represent the complete requirements for the exercise.** + +## Rationale for Test-Driven Development + +While it may seem like putting the cart before the horse, there are several good reasons why you might want to write unit tests before writing the implementation code: + +1. Design. + It forces you to think first about the design of the **interface** to the code, instead of jumping straight to the implementation. + Having a well-designed (and testable!) interface is often more important than having an efficient implementation. + +1. Discipline. + Writing tests is often seen as a chore or an afterthought; writing the tests _first_ guarantees that at the end of the day you will have written enough unit tests to cover most or all of your code's functionality (rather than possibly never getting around to it). + +1. Less Work. + If you apply a tight cycle of write one test, then write the code to implement that test, then write the next test, your code ends up growing organically. + This often (though not always) leads to less wasted effort; you end up writing all the code you need, and none of the code you don't need. + +## How does Exercism apply TDD? + +We've done the work of writing a unit test suite for you. +Your goal is to write a solution that contains just enough code to make all those unit tests pass, and no more. + +Should you choose to work with a mentor (and we encourage you to do that once you get the tests passing), they can help you refactor and refine your initial implementation, or even propose new unit tests. + +## Working in the online editor + +When you’re working in the code editor on Exercism’s website, you can read the tests but you are not able to edit them. +All tests will be executed each time you run them, regardless of any "skip" mechanisms noted in the test file. + +Test results will default to expanding the first failed test message (although what is displayed varies by track). + +Don’t be discouraged by a large number of failing tests. +Focus on making them pass one-by-one. + +## Working locally + +Many tracks use "skipped" tests in their test files. +Initially, only the first test is "active" and the remaining are deactivated (how this happens varies by track). +When you run the test suite in your environment, only the first test runs. +We do this to encourage you to follow this workflow: + +1. Before adding any new code, run the test suite: you should see a failing test. +1. Add _just enough_ code to pass the test. +1. Run the test suite. If the test still fails, repeat the last step. +1. Review your code and refactor as desired, making sure the tests still pass. +1. Once you have passed all the tests, congratulations you're done! +1. Otherwise, "unskip" the next test and goto 1. + +Exactly how tests are "unskipped" (or selected) depends on the track. +For some tracks, it might be commenting or removing an annotation. +For some tracks, it might be changing an attribute from true to false. +Take the time to read the track documentation: it will explain these details. + +## Further reading + +* [About Test-First Teaching](https://web.archive.org/web/20220918221108/http://testfirst.org/about) at the archived TestFirst\.org site. +* [Test-driven development](https://en.wikipedia.org/wiki/Test-driven_development) at Wikipedia. +* [Test Driven Development](https://exercism.org/docs/tracks/python/test-driven-development) on the Python track. From 69172026abbef77cc727dcf567db1bdf8395744b Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Thu, 23 Jan 2025 12:41:29 -0500 Subject: [PATCH 02/12] Apply suggestions from code review Co-authored-by: Jeremy Walker Co-authored-by: Anastasios Chatzialexiou <16361161+tasxatzial@users.noreply.github.com> --- using/solving-exercises/tdd.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index d38ff451..d6d8161b 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -4,11 +4,11 @@ Test-Driven Development (sometimes called Test-First Development or Test-Driven ## On Exercism, the tests _are_ the requirements! -Each exercise you work on will have some instructions describing in general terms what you need to do. +All Practice Exercises you work on (those ones that don't teach you a new concept) will have some instructions describing in general terms what you need to do. By design, these instructions do not account for programming-language-specific implementation details because they are shared by all of Exercism’s 70+ language tracks. Some language tracks will append more specific details for you, but not all of them do. -When you start working on an exercise, give the instructions a careful read. +When you start working on a Practice Exercise, give the instructions a careful read. They will give you a broad overview of how you go about implementing a solution. But you will have to read the _tests_ to understand the full and exact requirements: @@ -17,12 +17,12 @@ But you will have to read the _tests_ to understand the full and exact requireme - How are you expected to handle exceptions? And so on. You have solved an exercise when all the provided tests run and pass. -In other words, your solution is not just an interpretation the instructions that "looks right", your solution is a program that _satisfies the given tests_. +In other words, your solution is not just an interpretation of the instructions that "looks right", your solution is a program that _satisfies the given tests_. **The tests represent the complete requirements for the exercise.** ## Rationale for Test-Driven Development -While it may seem like putting the cart before the horse, there are several good reasons why you might want to write unit tests before writing the implementation code: +While it may seem like "putting the cart before the horse", there are several good reasons why you might want to write unit tests before writing the implementation code: 1. Design. It forces you to think first about the design of the **interface** to the code, instead of jumping straight to the implementation. From 03c05783e2f3f08badb7fba3192a72c09b7fb172 Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Thu, 23 Jan 2025 12:47:04 -0500 Subject: [PATCH 03/12] more review suggestions --- using/solving-exercises/tdd.md | 43 +++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index d6d8161b..865558b6 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -20,21 +20,6 @@ You have solved an exercise when all the provided tests run and pass. In other words, your solution is not just an interpretation of the instructions that "looks right", your solution is a program that _satisfies the given tests_. **The tests represent the complete requirements for the exercise.** -## Rationale for Test-Driven Development - -While it may seem like "putting the cart before the horse", there are several good reasons why you might want to write unit tests before writing the implementation code: - -1. Design. - It forces you to think first about the design of the **interface** to the code, instead of jumping straight to the implementation. - Having a well-designed (and testable!) interface is often more important than having an efficient implementation. - -1. Discipline. - Writing tests is often seen as a chore or an afterthought; writing the tests _first_ guarantees that at the end of the day you will have written enough unit tests to cover most or all of your code's functionality (rather than possibly never getting around to it). - -1. Less Work. - If you apply a tight cycle of write one test, then write the code to implement that test, then write the next test, your code ends up growing organically. - This often (though not always) leads to less wasted effort; you end up writing all the code you need, and none of the code you don't need. - ## How does Exercism apply TDD? We've done the work of writing a unit test suite for you. @@ -69,10 +54,30 @@ We do this to encourage you to follow this workflow: Exactly how tests are "unskipped" (or selected) depends on the track. For some tracks, it might be commenting or removing an annotation. For some tracks, it might be changing an attribute from true to false. -Take the time to read the track documentation: it will explain these details. +Take the time to read [the documentation for your track][track-docs]: it will explain these details. + +## Rationale for Test-Driven Development + +While it may seem like "putting the cart before the horse", there are several good reasons why you might want to write unit tests before writing the implementation code: + +1. Design. + It forces you to think first about the design of the **interface** to the code, instead of jumping straight to the implementation. + Having a well-designed (and testable!) interface is often more important than having an efficient implementation. + +1. Discipline. + Writing tests is often seen as a chore or an afterthought; writing the tests _first_ guarantees that at the end of the day you will have written enough unit tests to cover most or all of your code's functionality (rather than possibly never getting around to it). + +1. Less Work. + If you apply a tight cycle of write one test, then write the code to implement that test, then write the next test, your code ends up growing organically. + This often (though not always) leads to less wasted effort; you end up writing all the code you need, and none of the code you don't need. ## Further reading -* [About Test-First Teaching](https://web.archive.org/web/20220918221108/http://testfirst.org/about) at the archived TestFirst\.org site. -* [Test-driven development](https://en.wikipedia.org/wiki/Test-driven_development) at Wikipedia. -* [Test Driven Development](https://exercism.org/docs/tracks/python/test-driven-development) on the Python track. +* [About Test-First Teaching][test-first.org] at the archived TestFirst\.org site. +* [Test-driven development][tdd-wiki] at Wikipedia. +* [Test Driven Development][tdd-python] on the Python track. + +[track-docs]: https://exercism.org/docs/tracks +[test-first]: https://web.archive.org/web/20220918221108/http://testfirst.org/about +[tdd-wiki]: https://en.wikipedia.org/wiki/Test-driven_development +[tdd-python]: https://exercism.org/docs/tracks/python/test-driven-development From 6cb60efe113f1467431c4156a6e6594d71ffc685 Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Thu, 23 Jan 2025 12:48:26 -0500 Subject: [PATCH 04/12] broken link --- using/solving-exercises/tdd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index 865558b6..5f4dfe0c 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -73,7 +73,7 @@ While it may seem like "putting the cart before the horse", there are several go ## Further reading -* [About Test-First Teaching][test-first.org] at the archived TestFirst\.org site. +* [About Test-First Teaching][test-first] at the archived TestFirst\.org site. * [Test-driven development][tdd-wiki] at Wikipedia. * [Test Driven Development][tdd-python] on the Python track. From a1b3e881a6bc53cb63f16c25f85bc43b257c3c90 Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Thu, 23 Jan 2025 15:41:32 -0500 Subject: [PATCH 05/12] go beyond TDD --- using/solving-exercises/tdd.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index 5f4dfe0c..d21c0375 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -23,8 +23,10 @@ In other words, your solution is not just an interpretation of the instructions ## How does Exercism apply TDD? We've done the work of writing a unit test suite for you. -Your goal is to write a solution that contains just enough code to make all those unit tests pass, and no more. +Your goal is to write a solution that contains just enough code to make all those unit tests pass. +Keep this in mind: the TDD approach will help you get to the solution, but you don't need to stop there. +If you want to extend your solution beyond the requirements, you are welcome to do so. Should you choose to work with a mentor (and we encourage you to do that once you get the tests passing), they can help you refactor and refine your initial implementation, or even propose new unit tests. ## Working in the online editor From 13a392a524b4aa9fbdb82a7c53450060c00295dc Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Fri, 24 Jan 2025 11:41:39 -0500 Subject: [PATCH 06/12] Apply suggestions from code review Co-authored-by: Victor Goff --- using/solving-exercises/tdd.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index d21c0375..982f65a0 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -53,7 +53,7 @@ We do this to encourage you to follow this workflow: 1. Once you have passed all the tests, congratulations you're done! 1. Otherwise, "unskip" the next test and goto 1. -Exactly how tests are "unskipped" (or selected) depends on the track. +Exactly how tests are "unskipped" (or activated) depends on the track. For some tracks, it might be commenting or removing an annotation. For some tracks, it might be changing an attribute from true to false. Take the time to read [the documentation for your track][track-docs]: it will explain these details. From 6743b42cd8fce4947744b28cb8d7381f7f465602 Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Fri, 24 Jan 2025 11:43:15 -0500 Subject: [PATCH 07/12] review suggestions --- using/solving-exercises/tdd.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index 982f65a0..2912d98e 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -5,7 +5,7 @@ Test-Driven Development (sometimes called Test-First Development or Test-Driven ## On Exercism, the tests _are_ the requirements! All Practice Exercises you work on (those ones that don't teach you a new concept) will have some instructions describing in general terms what you need to do. -By design, these instructions do not account for programming-language-specific implementation details because they are shared by all of Exercism’s 70+ language tracks. +By design, these instructions do not account for programming-language-specific implementation details because they are shared by all of Exercism's 70+ language tracks. Some language tracks will append more specific details for you, but not all of them do. When you start working on a Practice Exercise, give the instructions a careful read. @@ -31,12 +31,12 @@ Should you choose to work with a mentor (and we encourage you to do that once yo ## Working in the online editor -When you’re working in the code editor on Exercism’s website, you can read the tests but you are not able to edit them. +When you're working in the code editor on Exercism's website, you can read the tests but you are not able to edit them. All tests will be executed each time you run them, regardless of any "skip" mechanisms noted in the test file. Test results will default to expanding the first failed test message (although what is displayed varies by track). -Don’t be discouraged by a large number of failing tests. +Don't be discouraged by a large number of failing tests. Focus on making them pass one-by-one. ## Working locally @@ -48,10 +48,11 @@ We do this to encourage you to follow this workflow: 1. Before adding any new code, run the test suite: you should see a failing test. 1. Add _just enough_ code to pass the test. -1. Run the test suite. If the test still fails, repeat the last step. +1. Run the test suite. + If the test still fails, repeat the last step. 1. Review your code and refactor as desired, making sure the tests still pass. 1. Once you have passed all the tests, congratulations you're done! -1. Otherwise, "unskip" the next test and goto 1. +1. Otherwise, "unskip" the next test and goto 1. Exactly how tests are "unskipped" (or activated) depends on the track. For some tracks, it might be commenting or removing an annotation. From 46c1376f0ef9aa4d27c2c261b704326c643e1a79 Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Sat, 25 Jan 2025 11:39:43 -0500 Subject: [PATCH 08/12] review suggestions --- using/solving-exercises/tdd.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index 2912d98e..16b43eb6 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -49,10 +49,16 @@ We do this to encourage you to follow this workflow: 1. Before adding any new code, run the test suite: you should see a failing test. 1. Add _just enough_ code to pass the test. 1. Run the test suite. - If the test still fails, repeat the last step. -1. Review your code and refactor as desired, making sure the tests still pass. -1. Once you have passed all the tests, congratulations you're done! -1. Otherwise, "unskip" the next test and goto 1. +1. If the test still fails, repeat step 2. +1. Once the test passes, refactor your code as desired, ensuring all the activated tests still pass. + Refactoring might include: + - removing any duplicated code, + - spliting long functions into smaller ones + - adding comments, etc. +1. "Unskip" the next test and repeat from step 1. + +Repeat these steps until you have unskipped all the tests. +Once all the tests are passing, congratulations, you have solved the exercise! Exactly how tests are "unskipped" (or activated) depends on the track. For some tracks, it might be commenting or removing an annotation. From 580f4a1228bd7b3cd289e52197ac624feb4df8ed Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Sat, 25 Jan 2025 16:37:12 -0500 Subject: [PATCH 09/12] "non-skip" tracks --- using/solving-exercises/tdd.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index 16b43eb6..80be7e80 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -65,6 +65,8 @@ For some tracks, it might be commenting or removing an annotation. For some tracks, it might be changing an attribute from true to false. Take the time to read [the documentation for your track][track-docs]: it will explain these details. +For tracks that don't skip the tests, applying this workflow may be as straightforward as commenting out the tests and uncommenting them one-by-one. + ## Rationale for Test-Driven Development While it may seem like "putting the cart before the horse", there are several good reasons why you might want to write unit tests before writing the implementation code: From 047e1d7419cb6c4382910eea41cbdfc250edefbf Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Mon, 27 Jan 2025 08:54:01 -0500 Subject: [PATCH 10/12] Apply suggestions from code review Co-authored-by: Isaac Good Co-authored-by: Anastasios Chatzialexiou <16361161+tasxatzial@users.noreply.github.com> --- using/solving-exercises/tdd.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index 80be7e80..98c2bb76 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -34,7 +34,9 @@ Should you choose to work with a mentor (and we encourage you to do that once yo When you're working in the code editor on Exercism's website, you can read the tests but you are not able to edit them. All tests will be executed each time you run them, regardless of any "skip" mechanisms noted in the test file. -Test results will default to expanding the first failed test message (although what is displayed varies by track). +When there are multiple tests that fail, three website initially only displays the results of the first failure. +You can click on other failures to expand them, too! +Sometimes the first result may not be the most informative. Don't be discouraged by a large number of failing tests. Focus on making them pass one-by-one. @@ -42,7 +44,7 @@ Focus on making them pass one-by-one. ## Working locally Many tracks use "skipped" tests in their test files. -Initially, only the first test is "active" and the remaining are deactivated (how this happens varies by track). +Initially, only the first test is "active" and the remaining are inactive (how this happens varies by track). When you run the test suite in your environment, only the first test runs. We do this to encourage you to follow this workflow: @@ -50,7 +52,7 @@ We do this to encourage you to follow this workflow: 1. Add _just enough_ code to pass the test. 1. Run the test suite. 1. If the test still fails, repeat step 2. -1. Once the test passes, refactor your code as desired, ensuring all the activated tests still pass. +1. Once the test passes, refactor your code as desired, ensuring all active tests still pass. Refactoring might include: - removing any duplicated code, - spliting long functions into smaller ones @@ -63,13 +65,13 @@ Once all the tests are passing, congratulations, you have solved the exercise! Exactly how tests are "unskipped" (or activated) depends on the track. For some tracks, it might be commenting or removing an annotation. For some tracks, it might be changing an attribute from true to false. -Take the time to read [the documentation for your track][track-docs]: it will explain these details. +Take the time to read [the documentation for your track][track-docs]; it will explain these details. For tracks that don't skip the tests, applying this workflow may be as straightforward as commenting out the tests and uncommenting them one-by-one. ## Rationale for Test-Driven Development -While it may seem like "putting the cart before the horse", there are several good reasons why you might want to write unit tests before writing the implementation code: +While it may seem like "putting the cart before the horse", there are several good reasons why you might want to write unit tests before writing the implementation code. 1. Design. It forces you to think first about the design of the **interface** to the code, instead of jumping straight to the implementation. From d83afc0136c3a1fdb6dfbe0f53c029a94d3ebc31 Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Mon, 27 Jan 2025 08:55:57 -0500 Subject: [PATCH 11/12] review suggestion --- using/solving-exercises/tdd.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index 98c2bb76..e4678f41 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -74,7 +74,7 @@ For tracks that don't skip the tests, applying this workflow may be as straightf While it may seem like "putting the cart before the horse", there are several good reasons why you might want to write unit tests before writing the implementation code. 1. Design. - It forces you to think first about the design of the **interface** to the code, instead of jumping straight to the implementation. + It forces you to think first about your program's [interface][api] (how it exposes its functionality to the world), instead of jumping straight into how you will implement the code. Having a well-designed (and testable!) interface is often more important than having an efficient implementation. 1. Discipline. @@ -94,3 +94,4 @@ While it may seem like "putting the cart before the horse", there are several go [test-first]: https://web.archive.org/web/20220918221108/http://testfirst.org/about [tdd-wiki]: https://en.wikipedia.org/wiki/Test-driven_development [tdd-python]: https://exercism.org/docs/tracks/python/test-driven-development +[api]: https://en.wikipedia.org/wiki/API From ed3d50c0ac22872785330e195df042e55ea97cfb Mon Sep 17 00:00:00 2001 From: Glenn Jackman Date: Mon, 27 Jan 2025 14:54:21 -0500 Subject: [PATCH 12/12] Apply suggestions from code review Co-authored-by: Anastasios Chatzialexiou <16361161+tasxatzial@users.noreply.github.com> --- using/solving-exercises/tdd.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/using/solving-exercises/tdd.md b/using/solving-exercises/tdd.md index e4678f41..0589c4b5 100644 --- a/using/solving-exercises/tdd.md +++ b/using/solving-exercises/tdd.md @@ -34,7 +34,7 @@ Should you choose to work with a mentor (and we encourage you to do that once yo When you're working in the code editor on Exercism's website, you can read the tests but you are not able to edit them. All tests will be executed each time you run them, regardless of any "skip" mechanisms noted in the test file. -When there are multiple tests that fail, three website initially only displays the results of the first failure. +When there are multiple tests that fail, the website initially only displays the results of the first failure. You can click on other failures to expand them, too! Sometimes the first result may not be the most informative. @@ -55,7 +55,7 @@ We do this to encourage you to follow this workflow: 1. Once the test passes, refactor your code as desired, ensuring all active tests still pass. Refactoring might include: - removing any duplicated code, - - spliting long functions into smaller ones + - splitting long functions into smaller ones, - adding comments, etc. 1. "Unskip" the next test and repeat from step 1. @@ -86,9 +86,9 @@ While it may seem like "putting the cart before the horse", there are several go ## Further reading -* [About Test-First Teaching][test-first] at the archived TestFirst\.org site. -* [Test-driven development][tdd-wiki] at Wikipedia. -* [Test Driven Development][tdd-python] on the Python track. +- [About Test-First Teaching][test-first] at the archived TestFirst\.org site. +- [Test-driven development][tdd-wiki] at Wikipedia. +- [Test Driven Development][tdd-python] on the Python track. [track-docs]: https://exercism.org/docs/tracks [test-first]: https://web.archive.org/web/20220918221108/http://testfirst.org/about