The SSCCE

Short, Self Contained, Correct (Compilable), Example

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?

It is all in the name, really. Take a look at each part. The version you prepare for others to see should be:

  • Short (Small) - Minimise bandwidth for your example, do not bore the audience.
  • Self Contained - Ensure everything is included, ready to go.
  • Correct - Copy, paste, (compile,) see is the aim.
  • Example - Displays the problem you are trying to solve.

Short

This depends on the group or forum. For a public Usenet forum, most readers will stop reading by 20Kb, and start complaining at 30Kb.

Tricks for Trimming

If your GUI has 40 buttons not related to the problem, remove them. If they are related to the problem (you remove them and the problem disappears) put one or two back in, if the problem reappears, include only those one or two buttons.

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 your example to that alone.

If your problem is a GUI layout problem, trim all the processes (JavaScript/Java methods etc.) from behind it. On the other hand, if your app. has a GUI but the problem is the processing, trim the GUI to a minimal version.

If you are 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.

Problem Solved?

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 originates can, in itself, help you to solve it. You might look more closely at the part you cut out, and in doing so, spot the problem.

Even if you cannot see why the problem occurs, you have still made an important step: identifying (at least part) of the code involved.

If the code you are trimming 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.

Self Contained

It is important to ensure that the code you relate to others can be 'copied, pasted, compiled, run' so that they can help you quickly and with a minimum of fuss.

This means that after the code has been copied, pasted and compiled by those helping you, they can run it and see the results for themselves. It is the example of the problem.

You are much more likely to receive help if you do this.

How to make an example self contained.

If your code performs I/O to files, replace the file I/O with dummy data structures in problems that are unrelated to input/output.

If the problem is the input and you can use textual input, prepare a short example that can be copied for the actual file data.

Should the problem happen only under load, insert code to simulate that load. If a layout problem only occurs under particular circumstances, force those things to happen, if it is practical to do so.

Obviously there are things that cannot be included in an example that is posted to a usenet 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.

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.

Correct

If my example was correct, what would I be doing here?

(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 your example fits the accepted standards and protocols.

To achieve that, you need to:

  • Line width Keep the width of the lines in your example to under 62 characters wide. (but please do not 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). Sometimes line wrap does not cause any problem with the example, but it usually does, and means the lines need to be rejoined or reconstructed, before they work as you intend them.
    This small tool designed to help detect and avoid line wrap in code examples posted to usenet. Use the Text Width Checker (TWC) to ensure text remains within a specific width. TWC includes a button to Replace Tabs - this is important, since tab characters expand to large widths in some news clients, also causing lines to wrap and 'break' the example.
  • 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 you follow the conventions they are used to, you help them to do that.
  • Ensure your example is correct. Either the example compiles cleanly, or causes the exact error message about which you want help. To help check this, use the SSCCE Text Based Compiler, which provides a text box that code can be pasted for on-the-fly compilation checking.

Further tips:

  • Move all resources (CSS/JS/Java source, images etc.) to the same directory, so they are easier to administer, and easier to find.
  • Remove package statements from Java code.
  • 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.
  • Validate the example, where a validator is available.

Example

Make sure the code you post displays the problem!

You have worked on your 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.

Refresh your computer as well. Reboot it if necessary.

Now open the pages, or program, where the problem occurs. Is it still there?

Perhaps 99% of the time it is (maybe less if you are using a less reliable operating system).

Now, if the problem is still there, post your example.

Example - Extra Points

I wish I 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. I would not be typing this document now, I would be sunning myself on a beach in an exotic location, drinking still more exotic cocktails.

Why do people miss such an opportunity? Very few things are as tempting as a link to the problem. To a seasoned usenet helper, it is almost as tempting as a small bottle with the vague message 'drink me', ..or an exotic cocktail.

Having a group of people look at the problem helps you to identify and solve the problem at hand, as well as compatibility problems (which might be the cause of the problem all along).

Standards on the Internet

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.

To start with, browsers do not work the same. I am 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.

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.

Java Applets

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.

For a long time MicroSoft was shipping the Internet Explorer browser with an older version of Java (a version 1.1 JVM). After some events happened, MS put the latest Java engines into its browsers. Soon after that, they began to supply the IE with no JVM at all.

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 their own browser or, sometimes, see your Applet working perfectly.

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).

Why bother?

A very good question. Why go to all this effort?

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.

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 have done those things, haven't you?

If you waste the time and bandwidth of the other members of a public forum, you risk members of the group delivering short sharp rebukes.

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.

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.

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.

If you have 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 such as Elance. That is what such companies specialize in.

Free usenet forums are for people to learn.

Having said that:

Let us assume you are indeed genuine in your learning, you have a huge, complex system with an occasional, unpredictable bug, and you have searched the FAQ & Group, studied the manual or documentation and not produced an answer.

Feel free to describe the problem to the group; perhaps it is a basic misunderstanding on your part that can easily be cleared up.

I am not proposing that every single problem needs a SSCCE in order to be solved. I am also not suggesting an example is, or should be, compulsory.

It will, however, make people much more likely to help, and will therefore increase the chance of finding a solution.

Contributors

This document was written by Andrew Thompson.

Special thanks to Ryan Stewart, for his services in converting the first drafts to human readable form, and Lew Bloch, for reviewing the 2007 edits. Their proof reading and sub-editing skills were invaluable.

Promoters

The SSCCE would not be a useful debugging technique, or any sort of way to prepare code examples, if nobody knew what it meant. Here are some of the people who have done the most to "spread the abbreviation".

Usenet. Lew Bloch, Joshua Cranmer, Knute Johnson, Daniel Pitts, Dag Sunde, ..

Sun forums. Aniruddha-Here, Darryl.Burke , camickr "A picture (the SSCCE), is worth a thousand words", cotton.m, hiwa (webmaster of the 'algafield' site, that provides a mirror of the SSCCE document), JayDS, Jaspre, petes1234, prometheuzz, Rodney_McKay, uncle_alice, Yannix, zadok, ..

Thanks to Dave Minter, sponsor of the SSCCE.org site/mirror. Think 'SSCCE', and get organized. Thanks also to Daniel Pitts for the Virtual Infinity mirror.

Version History

Document last updated 2009-12-02

  • 2009-12-03
    • Corrected minor spelling mistakes.
    • Added Virtual Infinity to list of mirrors.
    • Vatidated document.
  • 2008-06-22
    • Added link to STBC (the client-side replacement for the JOLC - Java On-Line Compiler - mentioned below).
    • Added Darryl.Burke to list of promoters.
  • 2008-04-18
    • Added SSCCE.org link to mirrors (which is now a) list, at page bottom.
    • Thanked Dave Minter (sponsor of SSCCE.org).
  • 2007-11-23
    • Changed 'Compilable' to 'Correct' in page title and description.
    • Removed 'PSCode.codes' prefix from page title.
    • Changed section on 'How to make an example self contained', to the parts about images. Now suggest linking to an example image on the web.
    • Completely removed the word simple from the body of the document. This word occurred once in the 3rd last paragraph of the document body, and was replaced with the word 'basic'. An SSCCE might be quite complicated, in a very short example.
    • Changed the section relating to line width in a number of ways
      • Dropped mentions of 80 chars to 62 and 72 respectively.
      • Added note not to remove all indentation.
      • Added link to the TWC.
    • Added new sections 'Promoters' and 'Version History'.
    • Added anchors to H2 headers - Why Bother?, Contributors, Promoters, Bibliography, Version History.
    • Added anchors to H3 headers - Tricks for Trimming, Problem Solved?, How to make an example self contained, Example - Extra Points, Standards on the Internet, Java Applets.
    • Added anchors beyond main sections, to list items linewidth, nameconvention, & valid, also to twc, and every, a 'synonym' for compulsory.
    • Changed the document to be more 'mirror friendly' by suppressing visibility of the links down the left hand side of the document, instead showing a single link and the PSCode 'bar-codes' image at the bottom of the page.
    • Removed links to JSLint (now a commercial product at a different URL) and the JOLC (removed some time ago) from validation section.
    • From 'Correct' section, 'Ensure your example is correct' point.
      • Added 'Either the example compiles cleanly, or causes the exact error message about which you want help' to the end.
      • Moved validation links to 'Further tips'.
  • 2003-12 - the SSCCE document first published.

Bibliography

Code. Computer language source code such as (Java, JavaScript, C++..) as well as formatting and layout languages including web pages and stylesheets (HTML and CSS, jsp, php, cgi, asp..).

JVM. Java Virtual Machine, the emulator in which Java Applets run.

This document is a mirror of the SSCCE at http://pscode.org/sscce.html
Codes - in Morse code, as a barcode..

Current mirrors

© 2003, 2004, 2005, 2006, 2007, 2008 by Andrew Thompson. All rights reserved.
Web hosting compliments of
Java Web Hosting