You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: using/faqs.md
+26-20
Original file line number
Diff line number
Diff line change
@@ -30,35 +30,40 @@ To learn more about what it means for the devil to be in the details, check out
30
30
31
31
## The Basics
32
32
33
-
## I'm lost. Where do I go?
33
+
###I'm lost. Where do I go?
34
34
35
35
You're in luck.
36
36
Here's a [step-by-step guide][getting-started] to get you started.
37
37
38
38
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.
39
39
Refer to [Opening an Issue][opening-an-issue] below for instructions on how you can help us help others.
40
40
41
-
## I get the error "Sorry, we could not authenticate you from GitHub" when trying to log in. What should I do?
41
+
###I get the error "Sorry, we could not authenticate you from GitHub" when trying to log in. What should I do?
42
42
43
43
This means that GitHub isn't willing to verify who you are.
44
44
That can be because you chose not to give permission or it might be because your GitHub account is not properly configured.
45
45
A common problem is that you haven't verified your email address on GitHub.
46
46
You can check that in your [GitHub email settings][email-settings].
47
47
48
-
## How do I delete my account?
48
+
###How do I delete my account?
49
49
50
50
You can delete your account by following the link at the bottom of your [settings page][settings].
51
51
If your issue is with emails and notifications you can adjust that in [your personal preferences][personal-settings].
52
52
53
-
## How do I unlock exercises?
53
+
### What am I supposed to do to solve an exercise?
54
+
55
+
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.
56
+
This development methodology is a form of [Test-Driven Development][tdd].
57
+
58
+
### How do I unlock exercises?
54
59
55
60
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).
56
61
This is called [Learning Mode][learning-mode].
57
62
58
63
While we recommend using Learning Mode to progress through a track, you could [switch to Practice Mode][switching-modes] to unlock all exercises.
59
64
For more information, see [unlocking exercises][unlocking-exercises].
60
65
61
-
## Why have my unlocked exercises in the old site become locked?
66
+
###Why have my unlocked exercises in the old site become locked?
62
67
63
68
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).
64
69
This is called [Learning Mode][learning-mode].
@@ -71,24 +76,24 @@ For more information, see [unlocking exercises][unlocking-exercises].
71
76
72
77
## Exercism Command-line Client
73
78
74
-
## I can't submit! What should I do?
79
+
###I can't submit! What should I do?
75
80
76
81
The new site has a brand new command-line client, and also needs some extra metadata for your exercise.
77
82
Read about how to [upgrade your command-line client and migrate your solutions for the new site][upgrade-cli].
78
83
79
84
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].
80
85
If that doesn't help either, [open an issue][new-cli-issue] and we will help you get it sorted out.
81
86
82
-
## How do I check the version of my command-line client?
87
+
###How do I check the version of my command-line client?
83
88
84
89
The version command `exercism version` outputs the running version of the Exercism command-line client.
85
90
By running the version command with the latest flag `exercism version --latest` you can check if there is a newer version available.
86
91
87
-
## How do I upgrade to the latest version of the command-line client?
92
+
###How do I upgrade to the latest version of the command-line client?
88
93
89
94
The command `exercism upgrade` will upgrade to the latest available version of the command-line client if one is available.
90
95
91
-
## I get permission denied errors when upgrading! What should I do?
96
+
###I get permission denied errors when upgrading! What should I do?
92
97
93
98
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.
94
99
@@ -98,36 +103,36 @@ If your command-line client was installed manually, please check the path of the
98
103
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.
99
104
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].
100
105
101
-
## I get the "16-bit MS-DOS Subsystem" error dialog after upgrading on Windows. What should I do?
106
+
###I get the "16-bit MS-DOS Subsystem" error dialog after upgrading on Windows. What should I do?
102
107
103
108
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.
104
109
To resolve this issue remove the corrupt binary and reinstall the command-line client using the [interactive walkthrough][interactive-walkthrough].
105
110
106
111
## Mentored Mode
107
112
108
-
## My queue hasn't updated in a while - is there something wrong?
113
+
###My queue hasn't updated in a while - is there something wrong?
109
114
110
115
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.
111
116
This is not unusual and you should see movement fairly soon.
112
117
If you your wait is far longer than the average, refer to [Opening an Issue][opening-an-issue] below.
113
118
114
-
## How many mentors does my track have? I only see a handful on the website.
119
+
###How many mentors does my track have? I only see a handful on the website.
115
120
116
121
The website only shows mentors who have provided bio information for the website, not the actual number of mentors who are actively reviewing solutions.
117
122
Rest assured, there are mentors working through their queues so hang in there!
118
123
119
-
## I submitted the wrong solution / file. What can I do?
124
+
###I submitted the wrong solution / file. What can I do?
120
125
121
126
On the exercise page in question, navigate to "Your Iterations".
122
127
If the unwanted iteration is folded, click the circled arrow.
123
128
In the "dots" menu, select "Delete iteration".
124
129
125
-
## How can I report abuse or examples of bad mentoring?
130
+
###How can I report abuse or examples of bad mentoring?
126
131
127
132
Please check our [Code of Conduct][coc] for more information about our expectations of conduct.
128
133
If you would like to report something, please reach out to us at [[email protected]][mail-abuse] and we will try to fix or resolve the issue respecting both you and your privacy.
129
134
130
-
## Why can't I give feedback on representations?
135
+
###Why can't I give feedback on representations?
131
136
132
137
To give feedback on representations for a track, you need to pass the following three criteria:
133
138
@@ -137,17 +142,17 @@ To give feedback on representations for a track, you need to pass the following
137
142
138
143
## Improving Exercism
139
144
140
-
## This is great! How do I get involved?
145
+
###This is great! How do I get involved?
141
146
142
147
There are a few different ways - becoming a mentor, managing a language track or reporting (or addressing!) issues on GitHub.
143
148
You can see more on the [How to Contribute page][contribute].
144
149
145
-
## How do new language tracks get added to the site?
150
+
###How do new language tracks get added to the site?
146
151
147
152
A new language track gets created when a member of the community takes the lead on it and becomes a maintainer of the track.
148
153
If you'd like to get involved in helping set one up, there are [instructions here][new-language-request].
149
154
150
-
## Opening an Issue
155
+
###Opening an Issue
151
156
152
157
Before submitting an issue, be sure to check the relevant GitHub issue tracker to see if it has already been reported or resolved:
153
158
@@ -158,7 +163,7 @@ Before submitting an issue, be sure to check the relevant GitHub issue tracker t
158
163
You can search through issues (remove the `is:open` filter to include closed/resolved issues).
159
164
Try a few different keywords.
160
165
161
-
## What if my issue is not listed here or in GitHub?
166
+
###What if my issue is not listed here or in GitHub?
162
167
163
168
If your problem hasn't been resolved or reported, then create an issue in the appropriate repository by selecting the green **New issue** button.
164
169
@@ -169,7 +174,7 @@ Make sure to include the following information:
169
174
1. Instructions on how to reproduce the issue
170
175
1. If applicable, reference to any related issue using its issue number (formatted like #1203)
171
176
172
-
## What if there is an issue with language on the website?
177
+
###What if there is an issue with language on the website?
173
178
174
179
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.
175
180
Please specify if the issue is with the instructions or something language specific, using the template below.
@@ -209,3 +214,4 @@ If you have spotted a typo or if you have a suggestion for clearer language or i
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.
4
+
5
+
## On Exercism, the tests *are* the requirements!
6
+
7
+
Each exercise you work on will have some instructions describing in general terms what you need to do.
8
+
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.
9
+
10
+
Sometimes, a language track will append more specific details for you, but some tracks do not.
11
+
12
+
When you start working on an exercise, give the instructions a careful read.
13
+
They will give you a broad overview of how you go about implementing a solution.
14
+
But you will have to read the _tests_ to understand the full and exact requirements:
15
+
16
+
- Must the result be a particular kind of data structure?
17
+
- Must the result be sorted in some order?
18
+
- How are you expected to handle exceptions? And so on.
19
+
20
+
You have solved an exercise when all the provided tests run and pass.
21
+
In other words, you are required to write a program that **satisfies the given tests**, not an interpretation of the instructions.
22
+
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_.
23
+
**The tests represent the complete requirements for the exercise.**
24
+
25
+
## Rationale for Test-Driven Development
26
+
27
+
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:
28
+
29
+
1. Design.
30
+
It forces you to think first about the design of the **interface** to the code, instead of jumping straight to the implementation.
31
+
Having a well-designed (and testable!) interface is often more important than having an efficient implementation.
32
+
33
+
1. Discipline.
34
+
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).
35
+
36
+
1. Less Work.
37
+
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.
38
+
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.
39
+
40
+
## How does Exercism apply TDD?
41
+
42
+
We've done the work of writing a unit test suite for you.
43
+
Your goal is to write a solution that contains just enough code to make all those unit tests pass, and no more.
44
+
45
+
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.
46
+
47
+
## Working in the online editor
48
+
49
+
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.
50
+
All tests will be executed each time you run them, regardless of any “skip” mechanisms noted in the test file.
51
+
52
+
Test results will default to expanding the first failed test message (although what is displayed varies by track).
53
+
54
+
Don’t be discouraged by a large number of failing tests.
55
+
Focus on making them pass one-by-one.
56
+
57
+
## Working locally
58
+
59
+
Many tracks use “skipped” tests in their test files.
60
+
Initially, only the first test is “active” and the remaining are deactivated (how this happens varies by track).
61
+
When you run the test suite in your environment, only the first test runs.
62
+
We do this to encourage you to follow this workflow:
63
+
64
+
1. Before adding any new code, run the test suite: you should see a failing test.
65
+
1. Add _just enough_ code to pass the test.
66
+
1. Run the test suite. If the test still fails, repeat the last step.
67
+
1. Review your code and refactor as desired, making sure the tests still pass.
68
+
1. Once you have passed all the tests, congratulations you're done!
69
+
1. Otherwise, "unskip" the next test and goto 1.
70
+
71
+
Exactly how tests are “unskipped” (or selected) depends on the track.
72
+
For some tracks, it might be commenting or removing an annotation.
73
+
For some tracks, it might be changing an attribute from true to false.
74
+
Take the time to read the track documentation: it will explain these details.
75
+
76
+
## Further reading
77
+
78
+
*[About Test-First Teaching](https://web.archive.org/web/20220918221108/http://testfirst.org/about) at the archived TestFirst\.org site.
79
+
*[Test-driven development](https://en.wikipedia.org/wiki/Test-driven_development) at Wikipedia.
80
+
*[Test Driven Development](https://exercism.org/docs/tracks/python/test-driven-development) on the Python track.
0 commit comments