Thursday 12 September 2013

Short, Self Contained, Correct (Compilable), Example


This is a lazy post, as it's just linking to another article, and a bit of me wittering on. But so be it.

Maybe you read my article ages ago, "Need help? Know how to ask for it". Here's more advice along the same vein.

Peter Boughton (who doesn't appear to exist on social media, damn him!), is one of the most clued-up CFML dudes I know, and is the most helpful person - by far - on the ColdFusion feed on Stack Overflow. Today he was addressing a question on Stack Overflow, and was confounded by example code that didn't compile, thus making it a bit hard to work out what was wrong with it. Yeah, sure, he could wade through it and fix it and then run it, but - really - why should he have to? If you're asking for help, then you should be doing as much of the work as possible to present your problem, and the person helping you should only be doing the bare minimum of wading through your stuff to work out what's wrong with it. They should not be fixing your example code so that it can even run! In most of the help forums we are just volunteers, and we give up our time to help. So it'd be good for people to respect that idea, and minimise the amount of time we need to invest in getting your code working.

And the thing that most people really seem to not get is the code needs to fulfill the following criteria for it to be effective example code:

  • Short. Only the stuff that demonstrates the issue. Nothing that is not related to the issue. It's noise, and unhelpful.
  • Self-contained. It should be able to be copy and pasted and then executed. it can't have dependencies on other bespoke code, database connections, environmental considerations, etc.
  • Correct. Well obviously if one needs help with code there will be some problem with the code somewhere, but it should compile, and there should not be any problems with it that aren't directly related to the "thing" that you can't work out.
  • Example. Not just a swag of code copy and pasted from the middle of yer app. An example of the problem. A test case.

That's my summary of the very good doc that Peter pointed the person asking the question to. The doc is here: "The SSCCE: Short, Self Contained, Correct (Compilable), Example". If you ever need to ask for help with code… read and understand that. And as per my earlier article, also read and understand this one: "How To Ask Questions The Smart Way".

And don't waste people's time, when you're expecting them to help you.