18

I often use the term code snippet when trying to help users frame their coding questions.

How to create a Minimal, Complete, and Verifiable example is useful for developers because an MCVE more or less equates to a code snippet but is written more for those with IT than GIS backgrounds.

Many of those asking coding questions here are novice or infrequent coders and I think we need to provide some simple guidelines on how to write a code snippet suitable for inclusion in a GIS SE question.

I have some ideas on what to write for ArcPy and Python, and have written an answer here specific to ArcPy, but I think it would be useful to have answers from others, and also answers that work for other libraries and languages.

What should a piece of code look like before it can be described as a code snippet?


If anyone wants to write a GIS SE tailored answer on R, the Q&A How to make a great R reproducible example? from Stack Overflow may provide some inspiration.

  • 1
    I quite like the SSCCE, I think this outlines it well compared to the MCVE – Midavalo Feb 15 '17 at 23:02
  • As an incentive to anyone writing an answer to this question, I'll be happy to move the Accept checkmark across to their answer to try and get them some early upvotes. – PolyGeo Feb 15 '17 at 23:49
16

A code snippet that is included in a question here should not be just a copy/paste from a larger script that you are working on and it should not be that larger script in its entirety. It should be something concise that a potential answerer can copy/paste and be ready (or at least very near ready) to run a test on.

I'll describe what I think a code snippet for an ArcPy question should look like.

Start by setting your code aside, and working instead on a new empty test script. I usually call mine test.py.

Usually start that script with:

import arcpy

Ideally it should end up being no more than about a dozen lines. This is not always possible but it should be the aim.

Use copy/paste to bring in small parts of your original script until it can be run to see the same error, or copy large parts in and be prepared to remove most of it from the test script. The aim of this test script is purely to reproduce your error, so that you can ask about it. The rest of your original script is important to you, but rarely to someone who is trying to answer your question.

Do not include try/except statements. These are used so that you can trap and deal with errors in your real code but when trying to figure out why a snippet from it is not working they can mask the error messages that Python would otherwise show you.

It should not include functions unless they are absolutely necessary to your question. If part of your code includes something like:

def myFunction(param1,param2):
    print(param1)
    print(param2)
myFunction("A","B")

and if that is needed for your question perhaps simplify it as:

print("A")
print("B")

If it is a Python script tool then, instead of leaving us to guess what you may have entered into a tool parameter when you see your problem, change anything like:

fc = arcpy.GetParamaterAsText(0)

to:

fc = r"C:\temp\test.gdb\testFC" # a value that you have tested and know shows the problem

Before you post your code snippet, make sure that you have run the exact code snippet that you are about to post, and then show not just the code but also the full error message (script name and line number are invaluable) and any other output such as from print or arcpy.AddMessage statements.

Ideally, a potential answerer will simply copy/paste your code snippet into a script, run it, see the same error message and other output as you, and then think:

I see the same problem, and I'm keen to try and figure what is going on. I'm so glad that I did not have to ask for a dozen clarifications before I got to this point (which I wouldn't have done because I would have moved on).


Sometimes a person's coding style can be off-putting to a potential answerer who is deciding whether to volunteer their time to try and understand a question before trying to answer it.

One way to improve readability of Python/ArcPy code is to try and conform to PEP 8 -- Style Guide for Python Code.

  • 4
    I can live without the 'import arcpy', that's a given. A code snippet should have enough lines to set all the variables in the offending line(s), quite often 'good' lines need to be removed because they're not contributing to the error. Questions with too much code look like 'debug this for me' questions and that isn't what this site is about; it should be a single error with an error message (if possible) with only enough lines for context, this is true for any code not just arcpy. PolyGeo has made some good points with this question/answer. – Michael Stimson Sep 5 '16 at 1:08
  • @MichaelMiles-Stimson I only have import arcpy in there because I (and I am guessing other potential answerers) frequently forget to prepend it into code snippets that I copy/paste into my IDE for testing. It's only a minute or so that I waste on spotting, re-editing, and re-running the test but it all adds up to more volunteered time that could be used elsewhere. Suggesting to include import arcpy at the beginning also reinforces the idea that code snippets are about reproducing problems from starting Python, and not after any code known only to the asker has run. – PolyGeo Sep 5 '16 at 1:36
  • 5
    I agree with having the import in a snippet, but for other reasons. Mostly, I think you should include all of your imports (including arcpy) so that it's understood what's been loaded. This can be important in cases of aliasing ; if I see things like np.zeros, etc. then I assume there was an import numpy as np somewhere, but I'd rather not assume. Cases of from module import * are even worse... – Evil Genius Sep 6 '16 at 18:12
  • @EvilGenius I wonder whether I should also suggest that Python/ArcPy code snippets in questions should avoid including aliasing unless the question really needs to include it to see the symptoms. I suspect they are often only included because they have been copy/pasted from some other code snippet found somewhere else rather than the asker making a conscious decision to use them, and for me they usually make code less readable, especially for those still early in their ArcPy/Python learning journey like many of ours. – PolyGeo Sep 6 '16 at 21:35
  • I think it would be simpler to say what @MichaelMiles-Stimson pointed out: a code snippet should include definitions for all variables used and point out that this may include additional modules. – Evil Genius Sep 7 '16 at 11:14
  • Does your advice rule out clarifying code by writing in pseudo code (in whole or in part)? – alphabetasoup Sep 23 '16 at 21:42
  • 1
    @RichardLaw Not entirely - it would depend on how closely the pseudo code presented was to representing a code snippet that works up to where the asker is stuck. I know what I look for in every question, not just coding questions, is a serious attempt by askers at trying to answer their own question before posting. – PolyGeo Sep 23 '16 at 21:49
  • I think pseudo code is often a very good indication of someone having thought about their issue in enough depth to make a good question. A high proportion of coding issues I see here are related to syntax errors (which is fine for novice coders). For the rest, I would suggest using at least a little pseudo code certainly aids clarity (e.g. a string representing a file path shouldn't be a 100-character string to an actual location on the asker's computer, or summarising the intention of a for loop without showing its contents if they are clearly not relevant). – alphabetasoup Sep 23 '16 at 22:00
  • 1
    @RichardLaw Anything that is clearly not relevant would seem to be a perfect candidate for being omitted from a code snippet altogether. There should never be the need for a 100-character string to an actual location on the asker's computer because that should always be replacable by something like r"C:\temp\test.gdb\testFC" in testing by the asker and/or their potential answerers. I know that the less guessing and synthesizing of a user's question that I have to do to perform a test, makes it all the more likely that I will find time to do so. – PolyGeo Sep 23 '16 at 22:21
  • 1
    I think changing a 100-character string to something like r"C:\temp\test.gdb\testFC" is potentially also a valuable part of the testing by the user - it could/should at least verify that the issue isn't with their long path (rules that out for answerers) – Midavalo Sep 24 '16 at 3:43

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .