SSCCE will soon be moving right here to the Wiki!

[Andrew Thompson]

After discussions with Jeanne Boyarsky on The SSCCE.org document will soon be disappearing, it seems set that the SSCCE will be moving right here to the Wiki.

Since the domain will also ideally move, there is no reason to put the temporary URL to the version of the document that will appear here. The link is in the original thread if you need it.

[Andrew Thompson]

Jeanne Boyarsky wrote:Step one completed: (document available at coderanch URL)

It is looking like a very faithful reproduction. Now we need to trim some things, make a few updates and make it 'at home' here.

Trimming:

I'd remove the row of links at the top. They really serve no purpose, given the list almost immediately below.

The last three sections: Contributors, Promoters & Version History as well as..

The Bibliography (that information could be in-lined where the term is defined)

All the 'bottom' of page links to mirrors etc. (one mirror at algafield seems to have disappeared, and the other won't be a mirror for long).

Updates:

Under Short section "stop reading by 20Kb, and start complaining at 30Kb.". That is a wildly huge amount of code to call 'short'. It should be changed from Kb to 'lines of code', but how should those values be adjusted? I think the upper limit should be based upon, and refer to, how much code a user of Java Ranch/Code Ranch can actually post in a question. I cannot speak for this forum, but another popular forum seems to hit a limit in around 600 to 650 lines of (properly formatted) code. The 'stop reading' part can probably be stated as 200 lines of code.

Under the Correct section, remove the 2nd paragraph of the first point that refers to the Text Width Checker Java tool. Doing text width checks is easy in most editors designed for editing code/HTML. Plus the entire PSCode.org will probably be disappearing (as was the fate for the SSCCE until the kind offer from Java Ranch to provide it a home on the Wiki)

The same applies to the SSCCE Text Based Compiler mentioned in the 3rd point.

Rework it to remove every reference of "I", "I'm" etc. to a "we" or alternate wording. Sections to look at are Example - Extra Points, and the emboldened section near the end of Why bother?

At home:

How does a page gain the usual Wiki page wrapper and styles?

[Jeanne Boyarsky]

Andrew,
Our first goal is transfer the domain. Then we decide if we want to keep it as an HTML page (with CodeRanch styling) or make it a wiki page with a redirect to the new page. We'll probably decide that in March.

Priority one is to make sure the page doesn't disappear!

[Andrew Thompson]

Jeanne Boyarsky wrote:..We'll probably decide that in March.

Yes, that is fine. No rush.

[Jeanne Boyarsky]

Yes, I meant March . Edited that in.

[Jeanne Boyarsky]

We decided to leave the doc as is rather than move it to the wiki. At least for the time being.

We just changed the hosting info at the bottom to reflect our hosting provider and a coderanch link.

[Andrew Thompson]

Jeanne Boyarsky wrote:..We just changed the hosting info..

That is subtle.

How about I provide as (code formatted) text, an HTML 5 validated version of the document with the changes I suggested earlier, but keeping the new hosting info.?

HTML 5 is definitely the way forward.

[Jeanne Boyarsky]

Andrew Thompson wrote:That is subtle.

It was the smallest change we could make to check the DNS was updated.

Andrew Thompson wrote:How about I provide as (code formatted) text, an HTML 5 validated version of the document with the changes I suggested earlier, but keeping the new hosting info.?

Sure. My biggest problem at the moment is lack of time. If you send the new page to me, I'll replace it.

[Andrew Thompson]

Jeanne Boyarsky wrote:

Andrew Thompson wrote:How about I provide as (code formatted) text, an HTML 5 validated version of the document with the changes I suggested earlier, but keeping the new hosting info.?

Sure. My biggest problem at the moment is lack of time. If you send the new page to me, I'll replace it.

Stats

Statistics comparing the old and new forms of the document. The new document is around 40% less 'page downs' and over 50% less to download.

##Long
Characters:	26126
Words:		4249
Screens:	10

##Short
Characters:	13042
Words:		2376
Screens:	6

Characters:	49.92%
Words:		55.92%
Screens:	60.00%

Source

The HTML 5 (validated) source of the newer form.

<!doctype> <html> <head> <meta http-equiv="content-type" content="text/html; charset=utf-8"> <title>Short, Self Contained, Correct Example</title> <meta name="author" content="Andrew Thompson edited by Ryan Stewart & Lewis Bloch"> <meta name="description" content="Describes the short, self contained, correct example. A useful technique for debugging."> <meta name="last-updated" content="2014-02-19"> <meta name="keywords" content="bug, debug, problem, fix, help, example, source, code, java, javascript, html, css, styles, layout"> <style type='text/css'> .centerFooter { text-align: center; font-size: 90%; } body { font-size: 100%; font-family: helvetica, arial, sans-serif; background-color: rgb(250,247,241); } </style> </head> <body class="nopad"> <h1>The SSCCE</h1> <h2>Short, Self Contained, Correct (Compilable), Example</h2> <p>If you are having a problem with some code and seeking help, preparing a Short, Self Contained, Correct Example (<abbr title='Short, self contained, correct example'>SSCCE</abbr>) is very useful. But what is an SSCCE?<p> <p>It is all in the name, really. Take a look at each part. The version prepared for others to see should be:</p> <ul> <li><a >Short</a> (Small) - Minimise bandwidth for the example, do not bore the audience.</li> <li><a >Self Contained</a> - Ensure everything is included, ready to go.</li> <li><a >Correct</a> - Copy, paste, (compile,) see is the aim.</li> <li><a >Example</a> - Displays the problem we are trying to solve.</li> </ul> <h2><a id='short' rel="nofollow">Short</a></h2> <p>This depends on the group or forum. For a public forum, most readers will stop reading by 100 lines of code, and start complaining at 250-300 lines of code.</p> <h3><a id='trim' rel="nofollow">Tricks for Trimming</a></h3> <p>If the GUI has 40 buttons not related to the problem, remove them. If they <em>are</em> related to the problem (you remove them and the problem disappears) put one or two back in, if the problem reappears, include <em>only</em> those one or two buttons.</p> <p>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.</p> <p>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 <em>is</em> the processing, trim the GUI to a minimal version.</p> <p>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. </p> <h3><a id='solution' rel="nofollow">Problem Solved?</a></h3> <p>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 <em>originates</em> can, in itself, help to solve it. You might look more closely at the part cut out, and in doing so, spot the problem.</p> <p>Even if you cannot see why the problem occurs, you have still made an important step: identifying (at least part) of the code involved. </p> <p>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.<p> <h2><a id='selfcon' rel="nofollow">Self Contained</a></h2> <p>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. <p>This means that after the code has been copied, pasted and compiled by those helping, they can run it and <em>see</em> the results for themselves. It is the <a >example</a> of the problem.</p> <p>You are much more likely to receive help if you do this.</p> <h3><a id='selfcontained' rel="nofollow">How to make an example self contained.</a></h3> <p>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. </p> <p>If the problem <em>is</em> the input and textual input can be used, prepare a short example that can be copied for the actual file data. </p> <p> Should the problem happen only under load, insert code to simulate that load. If a layout problem only occurs under particular circumstances, <em>force</em> those things to happen, if it is practical to do so. </p> <p> 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. </p> <p>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. </p> <h2><a id='co' rel="nofollow">Correct</a></h2> <blockquote>If my example was correct, <em>what would I be doing here?</em></blockquote> <p>(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. </p><p> To achieve that, it is necessary to: </p> <ul><li><a id='linewidth' rel="nofollow">Line width</a> Keep the width of the lines in the example to under 62 characters wide. (but please do <b>not</b> 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). <em>Sometimes</em> line wrap does not cause any problem with the example, but it <em>usually</em> does, and means the lines need to be rejoined or reconstructed, before they work as intended. <br>Most code/source editors will show a column width along the top of the editing area. </li> <li><a id='nameconvention' rel="nofollow">Use the naming convention</a>, 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. </li> <li><a id='valid' rel="nofollow">Ensure the example is <em>correct</em>. </a> Either the example compiles cleanly, or causes the exact error message about which needs solving. </li> </ul> <p>Further tips: </p> <ul> <li>Move all resources (CSS/JS/Java source, images etc.) to the same directory, so they are easier to administer, and easier to find. <li>Remove package statements from Java code. <li>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. </li> <li>Validate the example, where a validator is available. <ul> <li><abbr title='HyperText MarkUp Language'>HTML</abbr> <a href='http://validator.w3.org/' rel="nofollow">validator</a></li> <li><abbr title='Cascading Style Sheets'>CSS</abbr> <a href='http://jigsaw.w3.org/css-validator/' rel="nofollow">validator</a></li> </ul> </li> </ul> <h2><a id='eg' rel="nofollow">Example</a></h2> <p><em>Make sure the posted code, displays the problem!</em> </p><p> 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. </p><p> <em>Refresh the computer as well.</em> Reboot it if necessary. </p><p> Now open the pages, or program, where the problem occurs. Is it still there? </p><p> Perhaps 99% of the time it is (maybe less if using a less reliable operating system). </p><p> Now, if the problem is still there, post the example. </p> <h3><a id='extra' rel="nofollow">Example - Extra Points</a></h3> <p>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.</p> <p>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.</p> <p>Having a group of people look at the problem helps to identify and solve the problem at hand, as well as <em>compatibility problems</em> (which might be the cause of the problem all along).</p> <h3><a id='standards' rel="nofollow">Standards on the Internet</a></h3> <p> 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. </p> <p>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.</p> <p>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.</p> <h3><a id='devapplet' rel="nofollow">Java Applets</a></h3> <p> 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. </p> <p> For a long time MicroSoft was shipping the Internet Explorer browser with an <em>older version of Java</em> (a version 1.1 <abbr title='Java Virtual Machine, the emulator in which Java Applets run.'> JVM</abbr>). After some events happened, MS put the <em>latest Java</em> engines into its browsers. Soon after that, they began to supply the IE with <em>no JVM at all</em>. </p> <p> 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 <em>their own browser</em> or, sometimes, see the Applet working perfectly. </p> <p> 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). </p> <h2><a id='bother' rel="nofollow">Why bother?</a></h2> <p>A very good question. Why go to all this effort? </p> <p> 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. </p> <p> 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 <em>have</em> done those things, haven't you? </p> <p> If wasting the time and bandwidth of the other members of a public forum, you risk members of the group delivering short sharp rebukes. </p> <p> 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. </p> <p> 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. </p> <p> 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. </p> <p> 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.</p> <p>Free forums are for people to learn.</p> <p>Having said that: </p> <p> Let us assume you are indeed genuine in your learning, you have a huge, complex system with an occasional, unpredictable bug, and you <em>have</em> searched the FAQ & Group, studied the manual or documentation and not produced an answer. </p> <p> Feel free to describe the problem to the group; perhaps it is a basic misunderstanding on your part that can easily be cleared up. </p> <p><b><a id='compulsory' rel="nofollow">We</a><a id='every' rel="nofollow"></a> 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.</b></p> <p>It will, however, make people much <em>more likely to help</em>, and will therefore <em>increase the chance of finding a solution</em>.</p> <div class='centerFooter'> Web hosting compliments of <a href="http://evolutionhosting.com/pub/evolution.jsp" rel="nofollow">Evolution Hosting</a> and <a href="https://coderanch.com" rel="nofollow">CodeRanch</a>.<br> </div> </body> </html>

[Jeanne Boyarsky]

Thank you for making this a trivial activity for me. I've uploaded the new page.

And interesting stats on the page size!

[Andrew Thompson]

Jeanne Boyarsky wrote:Thank you for making this a trivial activity for me.

Thanks for your efforts at getting it to its new home.

Jeanne Boyarsky wrote:I've uploaded the new page.

Yes, that looks good.

How is the domain transfer & address redirection coming along? I'm still seeing the old document at SSCCE.org.

[Andrew Thompson]

Andrew Thompson wrote:How is the domain transfer & address redirection coming along? I'm still seeing the old document at SSCCE.org.

I am now seeing the new version of the document at SSCCE.org.

[Jeanne Boyarsky]

Andrew Thompson wrote:How is the domain transfer & address redirection coming along? I'm still seeing the old document at SSCCE.org.

I guess we are using different DNS servers. I've been seeing our version for days. The important thing is that everyone sees it by March 1st when your version goes down!

[Andrew Thompson]

Jeanne Boyarsky wrote:I've been seeing our version for days.

Admittedly, I have only been checking it on & off. OTOH I am in Australia and it takes a while for the changes to 'trickle through' the DNS chain.

Jeanne Boyarsky wrote:The important thing is that everyone sees it by March 1st when your version goes down!

(checks watch) I'd guess we're well placed to see that happen. Good work.