15
\$\begingroup\$

This is related to Why is hypothetical example code off-topic for Code Review?

Which is related to On-Topic question #3:

Is it actual code from a project rather than pseudo-code or example code?

It seems that we're not quite consistent in our treatment of "example code", which is what this meta post is for.

  • Which kind of "example code" questions do we want to avoid with this rule, and why?
  • Which borderline "example code" questions do we want to keep, and why?

I believe there are opinions and examples on both of these questions, so please bring on the examples and opinions and perhaps we can come to a conclusion on this topic.

\$\endgroup\$
  • \$\begingroup\$ I'm pretty convinced that the problem is we don't have the term "example code" defined anywhere. I'll take a stab at doing that later. \$\endgroup\$ – RubberDuck Jun 18 '14 at 1:37
10
\$\begingroup\$

Example Project vs Example Code

It's example code that we don't want to see. Example code is hard to review because it either:

  • lacks sufficient context (and/or)
  • has identifiers with names like foo and bar (and/or)
  • has methods with placeholder comments // ... instead of actual code

@200_Success does a better job at describing this, here (in an answer to the linked meta-question).

In my eyes, this aims at narrowing down the scope of the review, in getting a quickie that goes against rule #6 (which isn't being questioned here):

Do I want feedback about any or all facets of the code?

It's ok for your question to point out what kind of feedback you're mostly interested into.

It's not ok for your code to do that.


A question asking how could I reduce nesting in this code?, with the below code, would be off-topic:

if (foo)
{
    if (bar)
    {
        // do something
    }
}

Another question asking how could I reduce nesting in this code?, with an actual method and enough context to be able to tell what's going on and why, with the below code, would be on-topic:

public IActor FindActor(string search)
{
    if (search != "")
    {
        var actor = _repository.Actors.FirstOrDefault(actor => actor.Name.Contains(search));
        if (!actor == null)
        {
            return actor;
        }
    }

    return null;
}

Anyone else is biting their tongue to say "if (search != "") should be if (!string.IsNullOrEmpty(search))"? The two snippets could very well be 2 different revisions of the same question... by not narrowing it down and giving us real code to review, OP allows reviewers can pick up things that the OP didn't see... which is kind of the whole point!

Clarifications about where _repository is coming from can be addressed in comments, without any .

\$\endgroup\$
  • \$\begingroup\$ Could you expand on "example project?" What do you consider the topicality of an example project to be? It seems that an example project must be composed of example code, and therefore off-topic; do you see it differently? \$\endgroup\$ – Dagg Jun 18 '14 at 7:58
  • 1
    \$\begingroup\$ I'm not sure that I would agree with your second point (about identifiers). Would your example really be worse if we replace actor with fooObject? A real live example is this question: is it really harder to review because it contains someID instead of the actual id? \$\endgroup\$ – tim Jul 29 '14 at 14:48
  • \$\begingroup\$ Possibly off-topic, but what do you mean by exploding bear traps? \$\endgroup\$ – raptortech97 Aug 12 '14 at 13:36
  • \$\begingroup\$ @raptortech97 it's metaspeak referring to the not-so-gracious flames that can happen when voting to close a question, and OP isn't quite cooperating, resulting in a bunch of ugly comments and everyone feeling bad. Better avoid them exploding bear traps ;) \$\endgroup\$ – Mathieu Guindon Aug 12 '14 at 13:53
  • \$\begingroup\$ @Mat'sMug ah, thanks! \$\endgroup\$ – raptortech97 Aug 12 '14 at 13:54
2
\$\begingroup\$

What is an example?

Meriam Webster defines example as:

1 : one that serves as a pattern to be imitated or not to be imitated [a good example]

2 : a punishment inflicted on someone as a warning to others; also : an individual so punished

3 : one that is representative of all of a group or type

4 : a parallel or closely similar case especially when serving as a precedent or model

5 : an instance (as a problem to be solved) serving to illustrate a rule or precept or to act as an exercise in the application of a rule

So let's see where Alfred falls.

  1. The code does not seem to be a pattern to be imitated, but an imitation of a pattern. Alfred is not an example.
  2. Inapplicable to code.
  3. Alfred certainly is not representative of all a group or type. Alfred is not an example.
  4. The project is a parallel or closely similar case. In fact the project is meant as a learning exercise. The project is an example.
  5. The code is an exercise in the application of a rule (or pattern). The code is an example.

Alfred fails the common usage of the word example, not because the project is an example, but because the code is. Many of us feel that the project is an example, yet the code is not. That is at odds with the common usage of the word example. How can we feel it is not an example, if it clearly would be commonly defined as such? Because that the common usage of the word "example" isn't good enough for us. We (like scientists) must rigorously define what the word means to us.

Ok, so what is an example then?

An example is a piece of code that has had it's complexity stripped away.

I will also refer to @200_success's example. In that example, the complexity of a real piece of code had been stripped away. It was an attempt to limit the scope of the review. Which, as others have said, goes against the spirit of the site. Here is another example which has had it's complexity stripped away. I should not have cast that reopen vote. It is example code and it is off-topic.

What makes Aflred Different?

Alfred is different because it has not had it's complexity stripped away. It is functioning code that was purposely built as a learning exercise. It was not built one way, and then presented to us here as something else. It was given to us the way it was written.

I think that's the big test here. Was the code modified just for us? There no benefit in any OP posting code that they modified for the sake of posting here. Alfred wasn't modified just for us. So, it is on-topic.

\$\endgroup\$
  • \$\begingroup\$ I think when we talk about "example code" we are only talking about definition 5 and possibly 4, i.e. code that exists solely to illustrate a question, point or pattern, do you agree? If so it might be more straightforward to point that out before comparing Alfred to irrelevant definitions. \$\endgroup\$ – Dagg Jun 18 '14 at 20:17
  • \$\begingroup\$ My point was that we have not defined the word "example" well and need to do so. I have proposed my definition. I will not argue with you @Dagg. Feel free to post your own answer and let the community vote on it. \$\endgroup\$ – RubberDuck Jun 18 '14 at 20:20
  • \$\begingroup\$ I completely agree that we haven't defined it properly, and am not trying to argue, only suggesting that we throw out irrelevant definitions before comparing them to our subject. \$\endgroup\$ – Dagg Jun 18 '14 at 20:22
  • \$\begingroup\$ @Dagg I think it's a more complete argument the way it is. I'll think about it. \$\endgroup\$ – RubberDuck Jun 18 '14 at 20:23
  • \$\begingroup\$ My point is that if #1 and #3 don't apply to anything we would normally agree on as being example code, we shouldn't try to apply to the subject either, as it just muddies the water (just like #2). \$\endgroup\$ – Dagg Jun 18 '14 at 20:54
1
\$\begingroup\$

An example of an example project that's not example code:

The Alfred question were discussed quite a bit in chat last night.

I think that the Alfred question should stay as on-topic because:

  • The code is not example code. It is the project that has been constructed for reasons of learning some design patterns, but there's nothing wrong with that. The project has been finished and works perfectly fine. It even contains a JSFiddle
  • "It contains enough meat to be reviewable"
\$\endgroup\$

You must log in to answer this question.

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