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-22
Original file line number
Diff line number
Diff line change
@@ -30,34 +30,39 @@ 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 on the forum][forum].
39
39
40
-
## I get the error "Sorry, we could not authenticate you from GitHub" when trying to log in. What should I do?
40
+
###I get the error "Sorry, we could not authenticate you from GitHub" when trying to log in. What should I do?
41
41
42
42
This means that GitHub isn't willing to verify who you are.
43
43
That can be because you chose not to give permission or it might be because your GitHub account is not properly configured.
44
44
A common problem is that you haven't verified your email address on GitHub.
45
45
You can check that in your [GitHub email settings][email-settings].
46
46
47
-
## How do I delete my account?
47
+
###How do I delete my account?
48
48
49
49
You can delete your account by following the link at the bottom of your [settings page][settings].
50
50
If your issue is with emails and notifications you can adjust that in [your personal preferences][personal-settings].
51
51
52
-
## How do I unlock exercises?
52
+
### What am I supposed to do to solve an exercise?
53
+
54
+
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.
55
+
This development methodology is a form of [Test-Driven Development][tdd].
56
+
57
+
### How do I unlock exercises?
53
58
54
59
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).
55
60
This is called [Learning Mode][learning-mode].
56
61
57
62
While we recommend using Learning Mode to progress through a track, you could [switch to Practice Mode][switching-modes] to unlock all exercises.
58
63
For more information, see [unlocking exercises][unlocking-exercises].
59
64
60
-
## Why have my unlocked exercises in the old site become locked?
65
+
###Why have my unlocked exercises in the old site become locked?
61
66
62
67
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).
63
68
This is called [Learning Mode][learning-mode].
@@ -70,24 +75,24 @@ For more information, see [unlocking exercises][unlocking-exercises].
70
75
71
76
## Exercism Command-line Client
72
77
73
-
## I can't submit! What should I do?
78
+
###I can't submit! What should I do?
74
79
75
80
The new site has a brand new command-line client, and also needs some extra metadata for your exercise.
76
81
Read about how to [upgrade your command-line client and migrate your solutions for the new site][upgrade-cli].
77
82
78
83
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].
79
84
If that doesn't help either, [please post on the forum][forum] and we will help you get it sorted out.
80
85
81
-
## How do I check the version of my command-line client?
86
+
###How do I check the version of my command-line client?
82
87
83
88
The version command `exercism version` outputs the running version of the Exercism command-line client.
84
89
By running the version command with the latest flag `exercism version --latest` you can check if there is a newer version available.
85
90
86
-
## How do I upgrade to the latest version of the command-line client?
91
+
###How do I upgrade to the latest version of the command-line client?
87
92
88
93
The command `exercism upgrade` will upgrade to the latest available version of the command-line client if one is available.
89
94
90
-
## I get permission denied errors when upgrading! What should I do?
95
+
###I get permission denied errors when upgrading! What should I do?
91
96
92
97
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.
93
98
@@ -97,36 +102,36 @@ If your command-line client was installed manually, please check the path of the
97
102
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.
98
103
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].
99
104
100
-
## I get the "16-bit MS-DOS Subsystem" error dialog after upgrading on Windows. What should I do?
105
+
###I get the "16-bit MS-DOS Subsystem" error dialog after upgrading on Windows. What should I do?
101
106
102
107
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.
103
108
To resolve this issue remove the corrupt binary and reinstall the command-line client using the [interactive walkthrough][interactive-walkthrough].
104
109
105
110
## Mentored Mode
106
111
107
-
## My queue hasn't updated in a while - is there something wrong?
112
+
###My queue hasn't updated in a while - is there something wrong?
108
113
109
114
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.
110
115
This is not unusual and you should see movement fairly soon.
111
116
If you your wait is far longer than the average, refer to [Opening an Issue][opening-an-issue] below.
112
117
113
-
## How many mentors does my track have? I only see a handful on the website.
118
+
###How many mentors does my track have? I only see a handful on the website.
114
119
115
120
The website only shows mentors who have provided bio information for the website, not the actual number of mentors who are actively reviewing solutions.
116
121
Rest assured, there are mentors working through their queues so hang in there!
117
122
118
-
## I submitted the wrong solution / file. What can I do?
123
+
###I submitted the wrong solution / file. What can I do?
119
124
120
125
On the exercise page in question, navigate to "Your Iterations".
121
126
If the unwanted iteration is folded, click the circled arrow.
122
127
In the "dots" menu, select "Delete iteration".
123
128
124
-
## How can I report abuse or examples of bad mentoring?
129
+
###How can I report abuse or examples of bad mentoring?
125
130
126
131
Please check our [Code of Conduct][coc] for more information about our expectations of conduct.
127
132
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.
128
133
129
-
## Why can't I give feedback on representations?
134
+
###Why can't I give feedback on representations?
130
135
131
136
To give feedback on representations for a track, you need to pass the following three criteria:
132
137
@@ -136,24 +141,24 @@ To give feedback on representations for a track, you need to pass the following
136
141
137
142
## Improving Exercism
138
143
139
-
## This is great! How do I get involved?
144
+
###This is great! How do I get involved?
140
145
141
146
There are a few different ways - becoming a mentor, managing a language track or reporting (or addressing!) issues on GitHub.
142
147
You can see more on the [How to Contribute page][contribute].
143
148
144
-
## How do new language tracks get added to the site?
149
+
###How do new language tracks get added to the site?
145
150
146
151
A new language track gets created when a member of the community takes the lead on it and becomes a maintainer of the track.
147
152
If you'd like to get involved in helping set one up, there are [instructions here][new-language-request].
148
153
149
-
## Telling us when something is wrong
154
+
###Telling us when something is wrong
150
155
151
156
If you find something that's wrong, please let us know by creating a thread on [the forum][forum].
152
157
153
158
Before creating a thread, be sure to check for existing discussions.
154
159
Try a few different keywords.
155
160
156
-
## What if my issue is not listed here or on the forum?
161
+
###What if my issue is not listed here or on the forum?
157
162
158
163
If your problem hasn't been resolved or reported, then create a new [forum post][forum].
159
164
@@ -164,7 +169,7 @@ Make sure to include the following information:
164
169
1. Instructions on how to reproduce the issue
165
170
1. If applicable, reference to any related issue using its issue number (formatted like #1203)
166
171
167
-
## What if there is an issue with language on the website?
172
+
###What if there is an issue with language on the website?
168
173
169
174
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.
170
175
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
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
+
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.
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
+
Some language tracks will append more specific details for you, but not all of them do.
10
+
11
+
When you start working on a Practice Exercise, give the instructions a careful read.
12
+
They will give you a broad overview of how you go about implementing a solution.
13
+
But you will have to read the _tests_ to understand the full and exact requirements:
14
+
15
+
- Must the result be a particular kind of data structure?
16
+
- Must the result be sorted in some order?
17
+
- How are you expected to handle exceptions? And so on.
18
+
19
+
You have solved an exercise when all the provided tests run and pass.
20
+
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_.
21
+
**The tests represent the complete requirements for the exercise.**
22
+
23
+
## How does Exercism apply TDD?
24
+
25
+
We've done the work of writing a unit test suite for you.
26
+
Your goal is to write a solution that contains just enough code to make all those unit tests pass.
27
+
28
+
Keep this in mind: the TDD approach will help you get to the solution, but you don't need to stop there.
29
+
If you want to extend your solution beyond the requirements, you are welcome to do so.
30
+
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.
31
+
32
+
## Working in the online editor
33
+
34
+
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.
35
+
All tests will be executed each time you run them, regardless of any "skip" mechanisms noted in the test file.
36
+
37
+
When there are multiple tests that fail, the website initially only displays the results of the first failure.
38
+
You can click on other failures to expand them, too!
39
+
Sometimes the first result may not be the most informative.
40
+
41
+
Don't be discouraged by a large number of failing tests.
42
+
Focus on making them pass one-by-one.
43
+
44
+
## Working locally
45
+
46
+
Many tracks use "skipped" tests in their test files.
47
+
Initially, only the first test is "active" and the remaining are inactive (how this happens varies by track).
48
+
When you run the test suite in your environment, only the first test runs.
49
+
We do this to encourage you to follow this workflow:
50
+
51
+
1. Before adding any new code, run the test suite: you should see a failing test.
52
+
1. Add _just enough_ code to pass the test.
53
+
1. Run the test suite.
54
+
1. If the test still fails, repeat step 2.
55
+
1. Once the test passes, refactor your code as desired, ensuring all active tests still pass.
56
+
Refactoring might include:
57
+
- removing any duplicated code,
58
+
- splitting long functions into smaller ones,
59
+
- adding comments, etc.
60
+
1. "Unskip" the next test and repeat from step 1.
61
+
62
+
Repeat these steps until you have unskipped all the tests.
63
+
Once all the tests are passing, congratulations, you have solved the exercise!
64
+
65
+
Exactly how tests are "unskipped" (or activated) depends on the track.
66
+
For some tracks, it might be commenting or removing an annotation.
67
+
For some tracks, it might be changing an attribute from true to false.
68
+
Take the time to read [the documentation for your track][track-docs]; it will explain these details.
69
+
70
+
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.
71
+
72
+
## Rationale for Test-Driven Development
73
+
74
+
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.
75
+
76
+
1. Design.
77
+
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.
78
+
Having a well-designed (and testable!) interface is often more important than having an efficient implementation.
79
+
80
+
1. Discipline.
81
+
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).
82
+
83
+
1. Less Work.
84
+
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.
85
+
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.
86
+
87
+
## Further reading
88
+
89
+
-[About Test-First Teaching][test-first] at the archived TestFirst\.org site.
90
+
-[Test-driven development][tdd-wiki] at Wikipedia.
91
+
-[Test Driven Development][tdd-python] on the Python track.
0 commit comments