10

A commenter to an answer I recently posted said:

Please don't ignore errors in "example" code... You know some fool will blindly cut-n-paste it and... later make some other SO answerer's life difficult.

I'm torn on the subject. On the one hand I see the commenter's point (fools will do foolish things and it can clutter our exchanges with poor quality questions); however, code that demonstrates best practices (proper error handling, resource cleanup, etc) can often drown the gist of the idea in details that are not specific to the question/answer.

Should code samples explicitly handle errors and cleanup resources or is it ok to omit those (admittedly important parts) for the sake of brevity and clarity?

6
  • 6
    Idiots gonna idiot--you can't change that. Tho, I usually mark places where I've removed stuff I normally would have with a //snip or a <!-- yadda yadda --> just to indicate I'm highlighting certain parts of what would be a complete example.
    – user1228
    Commented Apr 14, 2015 at 18:31
  • 1
    @Will: ya, I also usually include comments like /* TODO: handle err */.
    – maerics
    Commented Apr 14, 2015 at 18:33
  • 1
    I leave out a lot error checking such as checking if a number field contains a valid number but will often add in the answer that it should be done if it's obvious by the OP's code that they aren't doing this.
    – codeMagic
    Commented Apr 14, 2015 at 18:34
  • I try to always submit working code. If the code in the question is broken and the broken part has nothing to do with the question, I often downvote and request clarification. If it's working code and just not all that great, i generally leave it alone unless i'm feeling overly helpful that day.
    – Kevin B
    Commented Apr 14, 2015 at 18:35
  • 1
    I personally believe that if questions need 'relevant code samples', then the same should hold for answers. Unless the question specifically asks about error handling, then it's superfluous to add that in. With that said, someone who goes that extra mile would be more likely to get an upvote from me.
    – Bardicer
    Commented Apr 14, 2015 at 19:13
  • 2
    Fresh from the battle field, an Example of the Day. The OP copied his code from a tutorial and did not add error checking. Maybe it wasn't mentioned, I'm too lazy foo to find out -- but hey! guess what! OP is mystified as to why his code is Not Working!
    – Jongware
    Commented Apr 14, 2015 at 19:47

5 Answers 5

8

There is no general rule. You'll need to evaluate, on a case by case basis, how much weight to grant to the brevity, clarity, completeness of any given post. You need to consider the context of the post to determine how likely readers of it are to be interested in brevity vs. completeness, how likely they are to be able to complete any given portion of an answer on their own, how likely they are to want/need to, to what degree adding additional content might confuse/intimidate readers or otherwise detract from the rest of the content, and of course, how useful/important the tangentially related content actually is.

It is up to each reader of each post to make their own judgement call on the post at hand. Different readers will of course have different values, and may choose to act on them accordingly when voting. As a post author, you need to best anticipate the needs of those readers in aggregate, to provide the content that you think will be most valuable to the largest portion of thoese reading your post.

2

I like to give two answers in these cases; an answer that directly answers their issue, and what the ideal answer should be.

These answers are contained together, and usually I'll have a header that tells you which is which.

Sometimes the OP just wants an answer, and that's fine, but we're not just helping out the OP, we're helping everyone who visits from Google; and that means making sure our answers are not just correct, but advised.

2

I would always prefer to omit error handling and resource cleanup unless it's directly related to the question.

We don't need to clutter questions with boilerplate stuff.

Certain things need to be implied, rather than explicitly stated, or we wind up explicitly stating them in practically every answer. Yes, you should always check return values for errors. You should never swallow all exceptions. You should never evaluate user-supplied input. You should sanitize your input and escape your output. On and on.

There are simply certain best practices that don't bear repeating in every answer when the best practice isn't directly related to the question.

5
  • Then give me a close flag/option something like "question has code that doesn't doesn't follow basic good practices" for cases where the question can't be answered due to the ignored errors (or for which that is the answer).
    – Dave C
    Commented Apr 14, 2015 at 18:45
  • 2
    @DaveC You want to close a question because they omitted error handling code?
    – user229044 Mod
    Commented Apr 14, 2015 at 18:47
  • The asker may very well be omitting boilerplate in order to provide a MCVE, @DaveC. In the other case, where the problem is caused by something that's obvious but not what they are directly asking about, just answer and point out the true problem. Imperfect code doesn't ipso facto mean a question is unanswerable or useless.
    – jscs
    Commented Apr 14, 2015 at 18:52
  • @maegar, when it's relevant to the question/answer, yes. Just as closing due to too vague or need more info, etc. Perhaps you are unaware of how frequent/annoying this is for Go questions on SO? Many of these are unanswerable without the errors (just like someone saying "Why does this fail" without saying what is failing).
    – Dave C
    Commented Apr 14, 2015 at 18:59
  • If the problem is solved by adding more error handling and reading the error message, that can be considered lack of research leading to a downvote and possibly a comment requesting said info, but i don't think it would necessarily need to be closed due to that (unless it also falls into a close reason)
    – Kevin B
    Commented Apr 14, 2015 at 19:01
2

A case-by-case basis is probably most appropriate but a good rule of thumb might be to include a sort of "standard disclaimer" like:

The example code below demonstrates the intent; however, make sure to check for errors, cleanup resources, etc.

This approach seems to combine the best of brevity in code example but also encouraging (diligent readers) to follow best practices.

3
  • 1
    And naturally, if it's does not obscure the point of the answer, nor is significantly longer, do the right thing. Commented Apr 14, 2015 at 19:06
  • @Deduplicator, exactly my point! In the Go Q&As where I see this "problem" it's can be just a matter of using v, err := … instead of v, _ := ….
    – Dave C
    Commented Apr 14, 2015 at 19:10
  • @DaveC: ya golang is kind of an interesting example because the language makes it easy to ignore errors. All too often on SO there are bad golang questions whose answers are are most likely clearly explained in an error message that the OP is simply ignoring...
    – maerics
    Commented Apr 14, 2015 at 19:12
1

[I'm the original commenter]

My opinion is that full example code should at minimum have a comment of some sort.

E.g. Instead of (Go example):

value, _ := Func1()
Func2(value)

do:

value, err := someFunc()
// check err!!
err = Func2(value)

(in particular, if the reader doesn't go to the documentation, like they should, they may not even realize Func2 returns an error). Also note, that at least for Go, just including err might be sufficient since an unreferenced variable is a compiler error, so it will be clear the code is incomplete. (E.g. how hard is it to say v, err := … instead of v, _ := …??)

By the way, I'm not actually referring to one or two line code snippets like I've shown here; I'm referring to otherwise fully complete functions or fully runnable example code (which, along with a play.golang.org link, appears to be the norm for Go answers here).

Although it's true that some people will just do foolish things and that can't be prevented; we can at least make it a little harder for someone that just doesn't know any better to start getting into bad habits.

The issue is that as much as we can blame the fools that cut-n-paste bad/incomplete examples into their own code, this happens. And then some other SO user has to waste time answering a question by someone that is ignoring errors.

8
  • 4
    It's not our job to predict how code will be used, and anticipate a lack of error handling. Such code distracts from the actual important parts of the answer. I think your // check err!! doesn't belong there, it's distracting from the actual meat of the answer.
    – user229044 Mod
    Commented Apr 14, 2015 at 18:35
  • 3
    A simple "/* error handling here*/" is too distracting???
    – Dave C
    Commented Apr 14, 2015 at 18:37
  • Yes, I think it is. You have an almost 1-to-1 ratio of error-handling code to content. In a longer answer, it's only going to make it harder to dredge through the code for the relevant bits.
    – user229044 Mod
    Commented Apr 14, 2015 at 18:38
  • I think this is unnecessary clutter for most situations. The times I would comment in the code are also times that the comments deserve a paragraph of their own. Like preventing SQL-injection. That would get both comments and potentially more explanation in the actual answer.
    – ryanyuyu
    Commented Apr 14, 2015 at 18:38
  • 1
    By the way, is "this answer is not useful" not actually the guideline for down votes on meta? I know on SO proper you're not suppose to downvote for only disagreement, is that different on meta?
    – Dave C
    Commented Apr 14, 2015 at 18:47
  • 2
    Yes; downvotes on meta indicate disagreement.
    – user229044 Mod
    Commented Apr 14, 2015 at 18:48
  • @meagar; okay, thanks. Normally I'd have taken it as a sign my answer was incorrect or deficient. I'm not a big meta user/reader.
    – Dave C
    Commented Apr 14, 2015 at 18:49
  • 2
    @DaveC On SO proper we don't allow posts that are all about whether the reader agrees or disagrees with an opinion because people will use their votes to reflect their opinions. On meta the content that is on topic doesn't allow for that, so there end up being a lot more votes based on the readers opinions. There is no difference in what is acceptable or even what the guidelines are, rather what's different is The content being voted on not the votes.
    – Servy
    Commented Apr 14, 2015 at 18:53

You must log in to answer this question.

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