SSCCE (Simple Self Contained Compilable Example), a term coined by Andrew Thompson
to
describe the desired form of code snippets posted in newsgroups.
If someone asks for a snippet or an short example to demonstrate a problem, they really mean a SSCCE, but just don’t want to use a potentially
unfamiliar term.
When you post some code on the Internet, your odds of getting help with it are
greatly improved if:
- It is short, not necessarily simple. Try to prune away
anything not strictly relevant to the problem. In the process of doing this, you
often solve your own problem. If you don’t prune, You are making the task
unnecessarily difficult for those you want to help you by clouding the issue with
irrelevancies, or hiding relevancies. If you don’t prune, you are implicitly
saying my time is valuable and yours is not., hardly a
winning attitude to solicit help. Purely out of self interest you should prune as
much as practical because if you ask only a small favour, that minimally
inconveniences, irritates or frustrates another, your chances of someone granting
it are much higher. You will also get more responses, which increases your odds of
getting a helpful, correct response.
- It is self-contained. This way others can compile and run the
code without having to compose test harnesses or look up additional code. With the
help of IDE (Integrated Development Environment)
s, debuggers etc, people can do far more than they can with raw eyeballs on a
non-compiling snippet. Almost never is the problem where the poster thinks it is.
If all he does is post a single line of code, it is like asking a cardiologist to
diagnose your heart troubles from a sperm sample. It is a waste of time asking
where the error is unless you post the code that contains the error. And since
you clearly don’t really know where the error is, you must post the
complete code. The devil is in the details. I can’t say it often enough,
you need to construct and post a tiny complete program that
demonstrates the problem. The problem is almost never where you thought was, or
else you would have already found it. It is nearly always in the part of the
program you did not reveal.
- It is compilable or at least correct. Nearly
always you can at least clear up compile-time errors on your own. See error messages for help in deciphering the
errors. If the problem is a truly intractable compiler error, at least get rid of
any others. Often clearing up the other errors mysteriously clears up the
intractable one. Always cut and paste so you post the exact code; don’t
retype it; or type something similar. You will drive your readers nuts if you
insert or remove typos in the process of manual transcription. Your readers will be
wasting time on errors that are not even in your code, or trying to makes sense of
code that does something quite different from the program you are describing in
your post. If you do this often, people will become angry with you and stop
helping. Correct does not imply working, just as tidy, formatted,
commented, properly named as possible.
- List the output and the output you expected. In a certain sense, your program
nearly always works perfectly. It is just that you misunderstood what that piece of
code was supposed to produce. It usually produces a result completely in
conformance with what you asked for; it is just not the result you wanted.
If you refuse to take the effort to create an
SSCCE,
and still expect others to help you, at least — Post the complete code!
When you post an error message, include the complete and exact text copy/pasted.
It will mean far more to experienced people than to you. Since listings don’t
have any line numbers, you need to manually indicate which lines error messages and
stack traces point to.
Some people have taken offense at my advice and counter I
can post any damn question I want, any way I want. I don’t have to follow your
prissy power-trippy rules! That is quite correct, you don’t; it is just
your odds of getting good responses are better if you follow this advice. Consider
that some posts on the newsgroups attract the most experienced people who debate
among themselves the optimal solution. Other posts are ignored or attract only a few
not very helpful responses. Some questions get few responses simply because they are
too difficult. Others do poorly for lack of following the advice above or for
ignoring the additional advice I give in the newsgroups entry. It is your choice. If you want better
responses to your questions, this is what in my experience, both as questioner and
answerer, will get them for you.
In the process of creating the SSCCE,
you often strip out the thing that is causing the trouble. 90% of solving a problem is knowing precisely what is broken.
Posting An SSCCE
Once you have your SSCCE you can post it to a newsgroup. Unfortunately, your
newsreader (or the newsreaders of those reading your SSCCE
) may break lines at odd points. Or the file may simply still be a bit too fat to
post. You can then post it on your website (plain or zipped) and post its
URL (Uniform Resource Locator)
or post your SSCCE
on Google docs and
post the URL
on the newsgroup. You can also post your code snippet on Pastebin or in a GitHub repository or even my website mindprod.com. Just email me your snippet and I will post it using
JDisplay .
Since the acronym SSCCE
is used only on newsgroups, you are free to
pronounce it to yourself any way you please. I suggest sskkee, a long
hissing s, stuttered k, then ee as in tree. Some
suggest ess ess cee cee ee. 
Sending An SSCCE
When you send someone an SSCCE
by email, don’t just embed it in the text of the message. The lines will wrap
and it won’t compile. Further, there is a good chance you will forget to send
everything, e.g. the imports. Send it as:
- an attachment
- a zipped attachment, especially if it is large or requires more than one
file.
- a link to where it is posted on the web
- a link to where it is posted on the web in a Subversion repository.
