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:
This depends on the group or forum. For a public Usenet forum, most readers will stop reading by 20Kb, and start complaining at 30Kb.
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 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.
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.
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.
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.
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:
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.
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).
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.
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).
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.
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.
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".
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.
Document last updated 2009-12-14
JVM. Java Virtual Machine, the emulator in which Java Applets run.