44

Suppose there's an example for a language feature that is bad practice to use.

I'd like to make a comment about this so future learners aren't led on the wrong path as so many have been before them. (Guess which language I'm talking about. :)

There doesn't appear to be a way to place a comment directly underneath an example.

Should I edit the example? But then everyone and their dog would start editorializing about coding styles and such so we can't have that. No?

I see a "Remarks" section further down; should I be using that?

7
  • 21
    "Guess which language I'm talking about." - Chicken?
    – Andy Mod
    Commented Jul 18, 2016 at 11:49
  • 8
    @Andy that one at least has consistent naming!
    – Pekka
    Commented Jul 18, 2016 at 11:54
  • 2
    I assume you're talking about PHP
    – cat
    Commented Jul 18, 2016 at 12:35
  • 17
    @cat PHP: encouraging to shoot yourself in the foot since 1995
    – Braiam
    Commented Jul 18, 2016 at 13:08
  • 3
    @Braiam More like PHP: encouraging you to shoot yourself and everyone you love since 1995
    – cat
    Commented Jul 18, 2016 at 13:10
  • 3
    @Braiam isnt that C in a nutshell, but since 1960? :)
    – Mafii
    Commented Jul 18, 2016 at 15:19
  • 2
    Instead of making a comment - why not make an edit suggestion to the code instead? Although I'd suggest if something is able to be classed as bad practice on documentation, it's probably too specific to be on there. Commented Jul 18, 2016 at 19:32

3 Answers 3

15

Suppose there's an example for a language feature that is bad practice to use

... now suppose that it makes sense under certain conditions. Document it like so:

The following example is the Way™ you should approach X problems with a context of ABC

my code is a rainbow!

This is however is not recommended when either A B or C is not present when doing X due reasons

I believe that topics on Documentation should be comprehensive pieces of useful informations, and obviously you don't document anti-patterns unless they are useful. Through I believe that is attractive the idea of a "Don't's" section, is better to instead say "do it this way only when these conditions are present, otherwise do it this other way". Humans (that read) tend to react positively to these approaches, unlike when you restrict them.

9

The Remarks section could be the right place for this sort of information. For instance, if you see several examples that do something dangerous with a language feature, it might be sensible to point out the pitfalls. Occasionally, there are language features that are only used by very new and very experienced users. (I'm thinking of things like goto and function-like macros.) It can be very helpful to warn people they are using powertools they might not have encountered before. (If there's just one hazardous example in a topic, it might be better to use an edit to add the note in the prose section of the example.)

In addition, if there's a safe alternative to a bad practice, be sure to add it as a competing example. That way, voting to can help readers avoid examples that might bite them down the road. Really bad examples will be voted down to the bottom of the page.

While constant bickering over coding styles is a potential problem, edits might be the best approach. Unlike Q&A, every edit must be approved by another user. Hopefully that will make edit wars less likely. (It will certainly make them inconvenient and slower moving.) Also unlike Q&A, editors gain reputation together from example upvotes. So if one editor adds a quick-and-dirty example and another cleans it up, both users benefit. Documentation, as designed, is more collaborative than Q&A.

One way to think of Documentation is the prescriptive/descriptive dichotomy. Some official documentation is purely descriptive in that it lists all features without having an opinion on when the feature should be used. Duplicating that effort would be a waste of time. On the other hand, purely prescriptive Documentation would presume there's some objective measure of good versus bad style. That's not the strength of Stack Overflow.

In an ideal world, the first example in a topic will be safe for anyone to use right out of the gate. But reading down page, it should be possible for people to find workarounds, overly-clever hacks, tricky-but-useful tricks, and perhaps even anti-patterns. The key is to give the reader the information either in the prose portion or in the Remarks to know which examples they should consider and which they should shun.

5
  • "Really bad examples will be voted down to the bottom of the page." Not if the mistake is subtle and there's no place to point it out.
    – Ben Voigt
    Commented Jul 24, 2016 at 22:00
  • @BenVoigt If it's just subtle, you can flag it [the current flag choices are not optimal, but you can just choose "unclear" and specify what's bad about it] or just go straight ahead and propose an improvement request.
    – bwoebi
    Commented Jul 24, 2016 at 22:02
  • @bwoebi: And what is a moderator who is not a subject matter expert supposed to do with such a flag?
    – Ben Voigt
    Commented Jul 24, 2016 at 22:13
  • @BenVoigt let's not discuss the same at two different places, see meta.stackoverflow.com/questions/329191/…
    – bwoebi
    Commented Jul 24, 2016 at 22:16
  • @BenVoigt: If a mistake is subtle, fix it with an edit or edit in a warning or edit out the example altogether.
    – Jon Ericson StaffMod
    Commented Jul 25, 2016 at 5:13
1

All examples I've seen (and/or written) added that into the example itself, if it's only relevant for this very example. At the same location, point out a better alternative. If you can't do this, why document the bad practice at all? Consider removing it completely.

It's different if it's applicable to the whole topic, that why the remarks section exists.

Edits because of a different code style should be avoided in general.

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