perltutorial
haukex
<p><small><i>This document is mirrored here from sscce.org with permission from Andrew Thompson, for details on authorship, copyright, etc. please see the [href://#sscce_bottom|bottom] of this page. The original document is targeted towards Java, JavaScript, HTML and CSS, but many of the same principles apply to Perl!</i></small></p>
<hr>
<h1>The SSCCE: Short, Self-Contained, Correct (Compilable) Example</h1>
<p>If you are having a problem with some code and seeking help,
preparing a Short, Self-Contained, Correct Example (SSCCE) is very
useful. But what is an SSCCE?</p>
<p>It is all in the name, really. Take a look at each part. The
version prepared for others to see should be:</p>
<ul>
<li>[href://#sscce_Short|Short (Small)] - Minimise bandwidth for the example,
do not bore the audience.</li>
<li>[href://#sscce_Self_Contained|Self-Contained] - Ensure everything is included,
ready to go.</li>
<li>[href://#sscce_Correct|Correct] - Copy, paste, (compile,) see is the aim.</li>
<li>[href://#sscce_Example|Example] - Displays the problem we are trying to solve.</li>
</ul>
<p>[href://#sscce_Why_bother|Why bother?]</p>
<h2><a name="sscce_Short"></a>Short</h2>
<p>This depends on the group or forum. For a public forum,
most readers will stop reading by 100 lines of code,
and start complaining at 250-300 lines of code.
<i>On PerlMonks, shorter examples of around 20 lines are recommended.</i></p>
<h3>Tricks for Trimming</h3>
<p>If the GUI has 40 buttons not related
to the problem, remove them. If they <em>are</em>
related to the problem (you remove them and the
problem disappears) put one or two back in,
if the problem reappears, include <em>only</em>
those one or two buttons.</p>
<p>The array or table that is causing a problem
may have a hundred entries, but again, if the
problem can be seen with two or three entries,
trim the example to that alone.</p>
<p>If the problem is a GUI layout problem,
trim all the processes (JavaScript/Java methods
etc.) from behind it. On the other hand, if
the app. has a GUI but the problem <em>is</em>
the processing, trim the GUI to a minimal
version.</p>
<p>If trimming a very large amount
if code for others to see, you might trim out
a part of it early on that you think is not
related to the problem, yet the problem is fixed.</p>
<h3>Problem Solved?</h3>
<p>By identifying more clearly where the problem
occurs, you have just made an important step toward
solving it. The process that highlights
where a problem <em>originates</em> can, in itself,
help to solve it. You might look more closely
at the part cut out, and in doing so, spot the
problem.</p>
<p>Even if you cannot see why the
problem occurs, you have still made an
important step: identifying (at least part)
of the code involved.</p>
<p>If the code being trimmed is now a concise
example of the problem, it is ready to present
to others, if not, put the problem code back
in and continue trimming other areas of the
code until it is.</p>
<h2><a name="sscce_Self_Contained"></a>Self-Contained</h2>
<p>It is important to ensure that the code
given to others can be 'copied, pasted, compiled,
run' so that they can help quickly and
with a minimum of fuss.</p>
<p>This means that after the code has been
copied, pasted and compiled by those helping,
they can run it and <em>see</em> the results
for themselves. It is the example of
the problem.</p>
<p>You are much more likely to receive help if you do this.</p>
<h3>How to make an example self-contained.</h3>
<p>If the code performs I/O to files,
replace the file I/O with dummy data structures in
problems that are unrelated to input/output.</p>
<p>If the problem <em>is</em> the input and textual input can be used, prepare
a short example that can be copied for the actual file data.</p>
<p>Should the problem happen
only under load, insert code to simulate
that load. If a layout problem only occurs
under particular circumstances,
<em>force</em> those things to happen, if
it is practical to do so.</p>
<p>Obviously there are things that cannot
be included in an example that is posted
to a forum, 'a database' etcetera,
but many times you just need a bit of
lateral thinking to come up with a way to
replace something you thought was 'vital'
to demonstrate a problem.</p>
<p>One example of lateral thinking is 'images'.
Images related to code problems might seem difficult
to replace. But one trick is to link to an image
available on the web, one that displays the same problem.
Try to make any web based images 'small' in bytes - if at all possible.</p>
<h2><a name="sscce_Correct"></a>Correct</h2>
<blockquote>If my example was correct, <em>what would I be doing here?</em></blockquote>
<p>(Laughs) No, that is not what 'correct' means in this context.
In this document, correct (or compilable, which particularly
relates to computer source code) means ensuring that
the example fits the accepted standards and protocols.</p>
<p>To achieve that, it is necessary to:</p>
<ul>
<li>Line width:
Keep the width of the lines in the
example to under 62 characters wide.
(but please do <b>not</b> remove all line indents!)
Newsreaders typically force a line wrap at
around 72 characters (and it pays to 'play it safe'
by using less than that).
<em>Sometimes</em> line wrap does not
cause any problem with the example, but
it <em>usually</em> does, and means the
lines need to be rejoined or reconstructed,
before they work as intended.
Most code/source editors will show a column width
along the top of the editing area.</li>
<li>Use the naming convention, if one exists.
Most of the people willing to help will be
using hints from the formatting of upper
and lower case letters, as well as their
descriptive names, to skim the code in
the hope of spotting the problem quickly.
If following the conventions the audience is
used to, it helps them to do that.</li>
<li>Ensure the example is <em>correct</em>.
Either the example compiles cleanly, or causes
the exact error message about which
needs solving.</li>
</ul>
<p>Further tips:</p>
<ul>
<li>Move all resources (CSS/JS/Java source, images etc.) to the same
directory, so they are easier to administer, and easier to find.</li>
<li>Remove package statements from Java code.</li>
<li>Demote public Java classes to default. If the language
specifies only a single public class per source code
file, demote all the other classes to default. This
allows the example to be compiled without being split
into separate files.</li>
<li>Validate the example, where a validator is available.
<ul>
<li>HTML (HyperText MarkUp Language) [http://validator.w3.org/|validator]</li>
<li>CSS (Cascading Style Sheets) [http://jigsaw.w3.org/css-validator/|validator]</li>
</ul>
</li>
</ul>
<h2><a name="sscce_Example"></a>Example</h2>
<p><em>Make sure the posted code, displays the problem!</em></p>
<p>You have worked on the example for hours, perhaps
days. It feels like forever. Now is a good time to
take a breather, step back, stretch, perhaps go for a
refreshing walk.</p>
<p><em>Refresh the computer as well.</em> Reboot it
if necessary.</p>
<p>Now open the pages, or program, where the problem
occurs. Is it still there?</p>
<p>Perhaps 99% of the time it is (maybe less if
using a less reliable operating system).</p>
<p>Now, if the problem is still there, post the example.</p>
<h3>Example - Extra Points</h3>
<p>We wish we had a dollar for every person who asked
for help about a web page or the stylesheet for one,
some JavaScript code, or a Java Applet - and did not
provide a link. We would not need to supply and maintain this document,
instead we would be sunning ourselves on a beach in an exotic
location, drinking still more exotic cocktails.</p>
<p>Why do people miss such an opportunity? Very
few things are as tempting as a link to the problem.
To a seasoned forum helper, it is almost as
tempting as a small bottle with the vague
message 'drink me', ..or an exotic cocktail.</p>
<p>Having a group of people look at the problem
helps to identify and solve the problem at hand,
as well as <em>compatibility problems</em> (which
might be the cause of the problem all along).</p>
<h3>Standards on the Internet</h3>
<p>Therein lies another 'gotcha' when dealing with
most things related to the internet.
The internet, as well as most things
associated with it, is just a little bit wild.
For every standard there are two alternates.
For every rule there are at least three exceptions
to the rule.</p>
<p>To start with, browsers do not work the same.
We are not just referring to differences between
IE and Netscape, or old and new browsers, but 'Internet
Explorer 5' for the Macintosh, for example, is a
(significantly) different browser from 'Internet
Explorer 5' for Windows.</p>
<p>People asking for help on web-design groups are often
surprised to hear that the problem they are
experiencing with a web page does not even
show for others using different browsers.</p>
<h3>Java Applets</h3>
<p>Another level of complexity, and more chance
of problems, is introduced when Applets are
in the web page. How the random clutch of browsers mentioned
above will react to (often poorly formed) html and styles,
with Applets thrown into the mix as well, is another
matter again. Here is just one example.</p>
<p>For a long time MicroSoft was shipping the
Internet Explorer browser with an <em>older version of Java</em>
(a version 1.1
JVM; Java Virtual Machine, the emulator in which Java Applets run).
After some events happened, MS put
the <em>latest Java</em> engines into its browsers. Soon
after that, they began to supply the IE with <em>no JVM
at all</em>.</p>
<p>Given the possible complications with Applets,
it is fortunate that they are so easy to check
when on they are on the internet. A few clicks
and someone on the other side of the planet
can be reading the output from the Java console
of <em>their own browser</em> or, sometimes, see the Applet
working perfectly.</p>
<p>If the Applet that fails for you works in someone else's browser,
it helps to quickly narrow the scope of the problem to the html,
the applet tag, or the JVM installed in the browser
(or complete lack of one).</p>
<h2><a name="sscce_Why_bother"></a>Why bother?</h2>
<p>A very good question. Why go to all this effort?</p>
<p>Perhaps someone can understand the problem
you describe from the description you give.
Maybe it is one of those things that a
thousand people before have stumbled on.</p>
<p>If you have already checked the FAQ,
Googled the forum, read the ..flaming
manual it is unlikely that an answer
will pop up that easily. You <em>have</em>
done those things, haven't you?</p>
<p>If wasting the time and bandwidth of
the other members of a public forum, you
risk members of the group delivering
short sharp rebukes.</p>
<p>The people who contribute to the groups
give a wide range of advice. Sometimes
the advice works, sometimes it does not,
but either way, the advice is free.</p>
<p>Contributors do so for a variety of reasons,
including the nice feeling they get when
they can pass on a piece of knowledge relating
to their chosen field to someone who is learning.</p>
<p>Unfortunately, if someone asks to be
spoon fed information that is contained
in a basic tutorial, it is a strong indication
that the questioner does not so much want
to learn as get others to do work they should
be doing themselves.</p>
<p>If there is a piece of code
and you wish to have it written, finished
or fixed by others, there are plenty of
avenues to achieve that. For a modest amount of
money, you can get most IT work completed (or done)
through a number of internet based outsourcing
companies.
That is what such companies specialize in.</p>
<p>Free forums are for people to learn.</p>
<p>Having said that:</p>
<p>Let us assume you are indeed genuine
in your learning, you have a huge, complex system
with an occasional, unpredictable bug, and you
<em>have</em> searched the FAQ & Group,
studied the manual or documentation and not
produced an answer.</p>
<p>Feel free to describe the problem to the
group; perhaps it is a basic
misunderstanding on your part
that can easily be cleared up.
</p>
<p><b>We are not proposing that every single
problem needs a SSCCE in order to be
solved. We are also not suggesting an
example is, or should be, compulsory.</b></p>
<p>It will, however, make people
much <em>more likely to help</em>, and will
therefore <em>increase the chance of
finding a solution</em>.</p>
<hr>
<p><a name="sscce_bottom"></a><small><i>This document is mirrored here from [http://sscce.org|sscce.org] with permission from Andrew Thompson, who as far as my research showed is the original author of this document (archive.org references: [https://web.archive.org/web/20140209102524/http://sscce.org/|sscce.org], [https://web.archive.org/web/20130809092415/http://athompson.info/contact.html|athompson.info]). sscce.org currently (Dec 2016) does not display any copyright notice, but used to say "© 2003-2010 by Andrew Thompson. All rights reserved." The document's current "author" HTML meta tag says "Andrew Thompson edited by Ryan Stewart & Lewis Bloch". A few very minor changes have been made, such adapting the HTML code for posting on this site, adding internal links, or adding a note with information specific to PerlMonks.</i></small></p>
<p>Additional resources for wisdom seekers on PerlMonks: [id://213052], [id://174051], and the [id://745674].</p>