-
Notifications
You must be signed in to change notification settings - Fork 3
Expand file tree
/
Copy patha1_help.html
More file actions
268 lines (255 loc) · 16.3 KB
/
a1_help.html
File metadata and controls
268 lines (255 loc) · 16.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>1. Getting help — Object-oriented Programming documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
<link rel="stylesheet" type="text/css" href="_static/fenics.css?v=8c7d05f9" />
<link rel="stylesheet" type="text/css" href="_static/proof.css" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css?v=fd3f3429" />
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/proof.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="2. Just enough Git to get by" href="a2_git.html" />
<link rel="prev" title="10. Further object-oriented features" href="10_further_object-oriented_features.html" />
<!--[if lte IE 6]>
<link rel="stylesheet" href="_static/ie6.css" type="text/css" media="screen" charset="utf-8" />
<![endif]-->
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-0EFVH5C4DC"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-0EFVH5C4DC');
</script>
<link rel="stylesheet" href="_static/featured.css">
<link rel="shortcut icon" href="_static/icon.ico" />
</head><body>
<div class="wrapper">
<a href="index.html"><img src="_static/banner.png" width="900px" alt="FInAT Project Banner" /></a>
<div id="access">
<div class="menu">
<ul>
<li class="page_item"><a href="index.html" title="Book">Book</a></li>
<li class="page_item"><a href="videos.html" title="Videos">Videos</a></li>
<li class="page_item"><a href="exercises.html"
title="Exercises">Exercises</a></li>
<li class="page_item"><a href="installation.html" title="Installation">Installation</a></li>
</ul>
</div><!-- .menu -->
</div><!-- #access -->
</div><!-- #wrapper -->
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="getting-help">
<h1><span class="section-number">1. </span>Getting help<a class="headerlink" href="#getting-help" title="Link to this heading">¶</a></h1>
<p>It is very likely that you will at some point find a programming problem you
can’t solve, or will find what you believe to be a bug in a piece of software
you rely on. In these circumstances, you need to be able to ask for help, in
writing, in some sort of online forum. There is a skill to doing this, and
doing it well will help others to help you - which radically increases the
chance that you will quickly get a solution to your problem. Such a request for
help is called an issue report. It’s sometimes also called a bug report, but
that’s not always a very accurate description: when you experience trouble with
a piece of software then you have an issue, the issue may or may not be the
result of a bug in the software.</p>
<section id="writing-an-issue-report">
<span id="issue-report"></span><h2><span class="section-number">1.1. </span>Writing an issue report<a class="headerlink" href="#writing-an-issue-report" title="Link to this heading">¶</a></h2>
<p>The following sections explain the content that should (and sometimes shouldn’t)
be in every issue report. You should get into the habit of thinking through all
of these stages every time you raise an issue. If the issue report is short then
there is no need to explicitly highlight each of these stages, so long as the
information is there. For a longer or more complex issue, it can make the issue
easier to read if you actually include these steps as subheadings.</p>
</section>
<section id="title">
<h2><span class="section-number">1.2. </span>Title<a class="headerlink" href="#title" title="Link to this heading">¶</a></h2>
<p>The title of the issue, which might go in the subject line of an email or a
forum post, should be a very short (10 word) outline of the key problem you
observe. Examples might include:</p>
<blockquote>
<div><p>Command not found when starting Python</p>
<p>Inverting matrix results in FloatingPointError</p>
<p>Incorrect values from MyClass.somemethod() for complex inputs</p>
</div></blockquote>
<p>What these titles have in common is that they (very briefly) contain both what
the user was doing, and what went wrong. This is enough for someone reading the
title to have a picture of what sort of thing the user was doing, and what
seems to have gone wrong.</p>
<p>Notice that the titles do not need to be full sentences (there are no verbs in
any of them), but they are precise about what the user was doing, naming the
exact operation and error observed.</p>
</section>
<section id="steps-to-reproduce">
<h2><span class="section-number">1.3. </span>Steps to reproduce<a class="headerlink" href="#steps-to-reproduce" title="Link to this heading">¶</a></h2>
<p>Next, it’s very important to establish exactly what has happened. This is
essential both for the understanding of the people trying to help, and to
enable them to recreate the problem themselves. It doesn’t need to be
particularly long, but it does need to be complete, in the sense that someone
else reading your description have enough information to know what you did and
(all else being equal), hit the same problem. The steps to reproduce can
themselves be divided into categories:</p>
<dl class="simple">
<dt>relevant system information</dt><dd><p>The key word here is “relevant”. For example if you’re having trouble running
Python itself, then which Python you installed on which operating system is
very relevant. On the other hand if Python is running just fine but you’re
hitting an <a class="reference internal" href="6_exceptions.html#term-exception"><span class="xref std std-term">exception</span></a> that you don’t understand, then it probably
doesn’t matter which operating system you are running.</p>
</dd>
<dt>which code failed</dt><dd><p>Were you working on a particular exercise, which one? How would the helper
find your code? If it’s code that you have edited, then unless you have
committed and pushed the changes, there is no way for a helper to get access
to the code you actually ran, so they will be flying blind. Avoid attaching
large amounts of code to issues, it’s difficult for helpers to work with, or
even to run in exactly the same way you did. It’s much better to be able to
point to a complete repository. Of course an even better approach is to construct a
<a class="reference internal" href="8_debugging.html#debugging-mfe"><span class="std std-ref">minimal failing example</span></a>.</p>
</dd>
<dt>what did you actually do?</dt><dd><p>This is one point where running code from the terminal is a major advantage,
because you can simply copy and paste everything you typed into the issue.
Explaining precisely what you did with a graphical interface is much harder,
and requires particular attention to detail. Remember that the person
reading your issue report can’t see what you can see, so if you skip over
steps then they might not even be able to see the thing you say you clicked
on!</p>
</dd>
</dl>
<p>It’s important that the description of what you did is strictly a factual
historical record. This is not the time to speculate about what you think is
going wrong, we’ll get to that bit. Here you’re strictly repeating what you did.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Please avoid posting substantially complete solutions to programming
exercises into a forum as this simply detracts from the learning experience
of others. The best thing to do is to reduce your issue to a <a class="reference internal" href="8_debugging.html#term-minimal-failing-example"><span class="xref std std-term">minimal
failing example</span></a> and post that. If that’s not possible and you’re posting
an issue as a part of a formal course with instructors, then ensure that
you have pushed your work to Github (<a class="reference internal" href="a2_git.html#commit-push"><span class="std std-numref">Section 2.6.6</span></a>), and then post
the git commit hash (<a class="reference internal" href="a2_git.html#git-hash"><span class="std std-numref">Section 2.6.7</span></a>). This will enable the instructor
to find your code. It is still important to include all of the other
components of the issue report.</p>
</div>
</section>
<section id="observed-result">
<h2><span class="section-number">1.4. </span>Observed result<a class="headerlink" href="#observed-result" title="Link to this heading">¶</a></h2>
<p>The next stage is to describe what happened. Again, this is strictly a
reporting stage. You report your observations and only those. If there is
textual output, then include all of it. It’s a very common failing for issue
reports to only contain the part of the output that the reporter thought was
relevant, omitting a whole load of essential information whose importance the
reporter did not realise.</p>
<p>If the problem is in the visual appearance of a graphical output, for example a
graph with invalid layout, then it would be appropriate to attach an image.</p>
</section>
<section id="expected-result">
<h2><span class="section-number">1.5. </span>Expected result<a class="headerlink" href="#expected-result" title="Link to this heading">¶</a></h2>
<p>This is the first point at which you are no longer simply a reporter of
observed facts. Sometimes the expected result is completely obvious: you
observed an error and you expected that the code would run correctly. However
in other circumstances there might not be an error but the result might not be
what you expect. Regardless of which of these is the case, you should include
some sort of statement of what you were expecting to have happen. This is for
two reasons, the first is that the mere fact of stating the question like this
forces you to think about what the core question you are asking is. This will
help you write a focussed issue report which is easier for your helpers to
respond to. The second is that a statement of what you think that the outcome
should be can help someone reading the issue report to understand the question
you are asking, and therefore that they should answer.</p>
</section>
<section id="any-other-information">
<h2><span class="section-number">1.6. </span>Any other information<a class="headerlink" href="#any-other-information" title="Link to this heading">¶</a></h2>
<p>Finally, you should add any other information you think is relevant. For
example if you think you have an idea about what is going on, then put it in
here. Alternatively if you’ve searched for the error online and think you’ve
found relevant information then include this here.</p>
</section>
<section id="issue-pitfalls">
<h2><span class="section-number">1.7. </span>Issue pitfalls<a class="headerlink" href="#issue-pitfalls" title="Link to this heading">¶</a></h2>
<p>Many issue reports suffer from a few common failings. A lot of these come down
to not providing enough or precise enough information for those who might help
to actually do so. Always remember that the people you are asking for help
haven’t seen what’s on your screen, and don’t know what have done. You
therefore need to spell things out for them in quite exacting detail.</p>
<section id="be-precise">
<h3><span class="section-number">1.7.1. </span>Be precise<a class="headerlink" href="#be-precise" title="Link to this heading">¶</a></h3>
<p>Rather than just say that you got an error, state exactly which type or, if you
don’t know, then repeat exactly what was printed out. Exactly which tool were
you using? Did a Python error occur in a particular script, or was it the
result of something you typed into the Python command line?</p>
</section>
<section id="don-t-leap-to-conclusions">
<h3><span class="section-number">1.7.2. </span>Don’t leap to conclusions<a class="headerlink" href="#don-t-leap-to-conclusions" title="Link to this heading">¶</a></h3>
<p>Very often you will have an idea about what has gone wrong. This is important
information, and you should include it in your issue report, however don’t let
it distract you from providing a precise and complete description of what
happened. If you’ve not been able to fix the issue yourself, then you can’t
exclude the possibility that you might not understand what it is that has gone
wrong. For this reason, you should always include everything you did and the
entirety of any error message, even if you don’t think it’s relevant to the
error.</p>
</section>
<section id="avoid-it">
<h3><span class="section-number">1.7.3. </span>Avoid “it”<a class="headerlink" href="#avoid-it" title="Link to this heading">¶</a></h3>
<p>“It doesn’t work” is every software developer’s least favourite issue report.
When describing the programs and data that you are using, you have a mental
model of what you are working with. The reader of your issue does not share
this model, so when you use pronouns such as “it” then the reader frequently
has no idea what “it” is that you are referring to. If you know which program
failed, then name the program explicitly. If you don’t then simply but
precisely describe what you observed.</p>
</section>
<section id="avoid-screenshots-of-text">
<h3><span class="section-number">1.7.4. </span>Avoid screenshots of text<a class="headerlink" href="#avoid-screenshots-of-text" title="Link to this heading">¶</a></h3>
<p>If the input and/or output of the operation which caused the issue are text,
then copy and paste that text into the issue. Do not insert a screenshot. There
are many reasons why screenshots are inferior to copying and pasting the text:</p>
<ol class="arabic simple">
<li><p>You don’t know what screen the reader will be on. Screenshots can very
easily end up very hard to read.</p></li>
<li><p>The reader can’t search the text in a screenshot for particular words or
phrases they need to find to diagnose your error.</p></li>
<li><p>The reader may well want to copy exactly what you typed in order to try to
reproduce the error. They can’t do that from a screenshot.</p></li>
<li><p>It is very easy for a screenshot to miss important information. For example
many error messages are quite long, and part of the error may well have
scrolled out of view.</p></li>
</ol>
<p>The only time when it is appropriate to include a screenshot is when the output
is graphical and you need to illustrate why something looks wrong.</p>
</section>
</section>
<section id="an-example-issue-report">
<h2><span class="section-number">1.8. </span>An example issue report<a class="headerlink" href="#an-example-issue-report" title="Link to this heading">¶</a></h2>
<p>This section shows a small example issue written on the forum system that
Imperial College London uses for its classes. The details of how to achieve the
right formatting will differ from forum to forum, but the principles are the
same. Importantly, most forum systems are optimised for making text easy to
read and will quite happily destroy the meaning of your code by moving the line
breaks to make the text fit the window. It’s therefore important that code is
correctly formatted as code rather than as text. On this forum, this is
achieved using the <kbd class="kbd docutils literal notranslate"><></kbd> icons. The plain icon is for inline code while the
boxed version is for code blocks. In this particular forum software, a
self-contained <a class="reference internal" href="8_debugging.html#term-minimal-failing-example"><span class="xref std std-term">minimal failing example</span></a> can be run directly in the
browser, providing additional information to helpers.</p>
<img alt="_images/edstem_issue.png" src="_images/edstem_issue.png" />
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer" role="contentinfo">
© Copyright 2019-2023, David A. Ham.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.4.7.
</div>
</body>
</html>