As beech highlighted, it would be easy enough to add this here:

----------------------

The SSCCE

Short, Self Contained, Correct (Compilable), Example

Adapted from the original, as preserved by a wayback machine Unfortunately, this is NOT short and appears to have been written with another language as its focus. However, f you substitute 'perl' for most references to 'java' this will feel more relevant. :-)

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 prepared for others to see should be:

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

Short

Tricks for Trimming

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

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 is the processing, trim the GUI to a minimal version.

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.

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 to solve it. You might look more closely at the part 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 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.

Self Contained

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.

This means that after the code has been copied, pasted and compiled by those helping, 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 the 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 textual input can be used, 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 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 the example fits the accepted standards and protocols.

To achieve that, it is necessary to:

1. Line width Keep the width of the lines in the 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 intended.
2. Most code/source editors will show a column width along the top of the editing area.
3. 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.
4. Ensure the example is correct. Either the example compiles cleanly, or causes the exact error message about which needs solving.

Further tips:

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

Example

Make sure the posted code, displays the problem!

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.

Refresh the 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 using a less reliable operating system).

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

Example - Extra Points

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.

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.

Having a group of people look at the problem helps 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. 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.

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 the 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 wasting 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 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.

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

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.

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

--------------------

This is offered in the hope that some monk(s) who is/are better at short will post their preferences on ways to make the adaptation shorter.

Hi ww,

If there are no copyright issues, then sure, I'd be all for just mirroring it here! But probably there's a better section for this kind of a node (perhaps as a root node) and a better title than the current one :-)

Some of the archived versions of the page appear to contain copyright info as well as now-dead links to mirrors, so I'm not sure what it means that the copyright has now been removed...

Update: In one of the older archived versions of the pages I have dug up what appears to be an e-mail address of the author, who I'm e-mailing asking permission to mirror the article. If I get a response I'll post back here.

Thanks,
-- Hauke D

Just a technical suggestion:

IIRC reducing the title to just SSCCE will facilitate linking to it with [SSCCE]

Cheers Rolf
_{(addicted to the Perl Programming Language and ☆☆☆☆ :)
Je suis Charlie!}

update

Yep just tested, will link directly :) (if it's unique otherwise will search for all titles with word as subset)

Hi LanX,

IIRC reducing the title to just SSCCE will facilitate linking to it

You're right, and that's what I did - interestingly, I wasn't allowed to post a one-word title initially, but editing the node allowed me to reduce the title down to one word.

Regards,
-- Hauke D

Hi,

You can always link an archived version like https://web.archive.org/web/20160926072757/http://sscce.org

or copy/paste the contents into a node you can link with SSCCE or perhaps SSCCE.org

Or maybe I should just rename this node exactly SSCCE :)

it seems http://www.sscce.org/ now points to ...

Um... Does it? I tried it just now and it DWIMmed. Maybe the domain registration was temporarily suspended? Or the DNS got attacked again?

Hi jdporter,

I tried it just now and it DWIMmed.

Yes, you're right, http://sscce.org is back up now. In the reply I got from Andrew Thompson, he mentioned that something may have gone wrong as some JavaRanch sites were switched from http to https.

Regards,
-- Hauke D

Hi all,

An update: Although sscce.org is back up now, as jdporter noted, I received a reply from Andrew Thompson that it's okay to mirror the document here, which I have now done at SSCCE - the node title should make it easy to remember when linking, as [SSCCE].

As for what else could be done with the node - such as perhaps moving it to a more appropriate section (?) or perhaps adding some more PerlMonks specific annotations, I'm open to suggestions.

Regards,
-- Hauke D

Okie dokie. As is my wont, I fscked around with things to make them "better". Namely:

1. The meditation haukex posted is now a tutorial. (It still needs a pedo to file it appropriately, however.)
2. The post now has a full, proper title.
3. The abbreviation, "SSCCE", is now the title of a "faqstring" node. (These are essentially kind of like alias nodes, useful for things like common acronyms.)
Check it: SSCCE
I reckon we are the only monastery ever to have a dungeon stuffed with 16,000 zombies.

Excellent. Thank you! And I hope/trust you thanked Mr. Thompson on behalf of our community.

... such as perhaps moving it to a more appropriate section ...

Yes, I think your intuition is good; it should probably be moved to the Tutorials section. I have placed a consideration on it for just that purpose. Thanks again!

I reckon we are the only monastery ever to have a dungeon stuffed with 16,000 zombies.

Great work Hauke! I think SSCCE would be improved greatly by the addition of a two-level linked section menu as in POD, and possibly the addition of a synopsis at the top. Maybe your excellent footnotes should be at the bottom and linked in the menu.

Thanks again.



The way forward always starts with a minimal test.

Is there a (relatively) easy way to search all your own posts for links to this site? I'd like to change mine to point to Beech's suggested archive, but if I went through over 500 posts I'd (a) be very bored and (b) be sure to miss something.

Regards,

John Davies

Update: thanks for the replies. I should have been able to do it myself, but I so rarely use Super Search that my unaided attempts failed and I couldn't work out a google recipe to give me what I wanted. I've now made the updates. If there's something either Super Search or I have missed, too bad.

This seems too obvious to be what you are looking for, but here it is anyway: did you try the Super Search? ?node_id=3989;BIT=sscce.org;a=davies

Found 3 nodes roughly between 2016-12-09 and 1999-10-04 (searched 100.00% of DB).

where any text contains "sscce.org"
written by any of davies

Date:	Author/owner:	Title:	Node type:
2015-06-23	davies	Re^3: save read-only Excel	Re:SoPW
2013-12-18	davies	Re^3: How to extract data from Excel by using Win32 OLE	Re:SoPW
2013-03-14	davies	Re: Extracting Chinese characters from Excel	Re:SoPW



The way forward always starts with a minimal test.

Hi davies,

Super Search appears to work even if the link is in the form [http://www.sscce.org/|foo].

Hope this helps,
-- Hauke D

Super Search allows you to specify a phrase, url, or other kind of target and to specify an author. Note the option to include a definition of "(separate strings with -- default is spaces) and -- of course -- the areas to search.

HTH. Seems to me a starting point, though you may have to wash-rinse-repeat with different flavors of soap (search terms) to be confident you haven't missed anything.

If I've misconstrued your question or the logic needed to answer it, I offer my apologies to all those electrons which were inconvenienced by the creation of this post.