21

The term "code snippet" is often used when trying to help users frame their coding questions.

Other similar terms can be found in:

and each term more or less equates to a code snippet, but they are written more for those with IT than GIS backgrounds.

Many of those asking coding questions here are novice (or infrequent) coders, and this FAQ is intended to provide some simple guidelines on how to write code snippets suitable for inclusion in GIS SE questions.

The first is written for ArcPy (and Python), but it would be useful to have answers that focus on other spatial libraries (and languages) too.

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.

0

1 Answer 1

18

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 near ready) to run a test on.

Here are some suggestions about what 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. This could be called test.py, it could be placed in a simple location (with no spaces in its pathname) like C:\temp, and simple feature class and shapefile names like C:\temp\testGDB\testFC and C:\temp\test.shp could be used. This can eliminate the possibility that a long path name is causing a problem.

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 to someone else's question).


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.

A PEP 8 level of strictness has been sought by some users, but is not required.

0

You must log in to answer this question.

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