Short Self-Contained Compilable
Example, a term coined by Andrew Thompson
to
describe the desired form of code snippets posted in
newsgroups. 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 IDEs, 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 leeast 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!
If you expect others to be able to diagnose the problem without the complete code, all they can do is make guesses based
on vaguely similar problems they once had themselves. If you are a newbie, chances are you will dream up thousands of
creative novel ways to write code that do not work. By refusing to post code, you are being as silly as a women who goes
to the doctor for help and refuses to disrobe or take any tests, and is angry when the doctor has no clue what the
matter with her is.
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.
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. If you don’t have a website, you can get a free one at Geocities,
or post your SSCCE on Google docs, and post the URL. You can also
post your code snippet at PasteBin.ca.
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.
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.
2008-03-13 by Roedy Green ©1996-2009 Canadian Mind Products
Please email your feedback for publication, errors, omissions, broken/redirected link reports
