"Code not yet written" clarification: Are unimplemented interfaces on- or off-topic?

Question

I would like to know what exactly it means. The reason for asking is my question which was recently put on hold:

https://codereview.stackexchange.com/questions/60108/async-task-queue-design

Can anyone please specify why the code I provided is considered "not yet written" and what is "written code" then? Any opinions?

Answer 1

I am happy to treat your question as a 'test case' for determining the scope of Code Review as part of the 'Beta site' definition of what is in scope.

It is my assertion, that your question is off topic. Any one of the following things makes your code off-topic:

1. Interfaces are a description of intent, not of implementation. Interfaces tell us what you want the code to do, not what the code actually does. As a result, there is no code to review, and we cannot tell you whether the code successfully implements the interface. Your question must include the code. An interface is not an implementation, it is a specification

2. you do not request a code review. Instead, you request three 'wants':

   • thread safety
   • code chunking
   • chunk-completion notification

   This suggests you are requesting features you do not yet have. To the best of my knowledge, does the code work? If you still want things from the code, then is it working yet?

3. Since we can't see the actual code, there is no way to tell whether it is actual code, or just vapourware. You tell us that it exists, but we can't see it. Is it actual code from a project rather than pseudo-code or example code? Since I can't tell, it's off-topic.

All three of those issues would have to be resolved before I would think that the code is on-topic.

As it stands, you are not looking for a code review, you are looking to discuss whether your design will meet your goals. Code Review is not the site for discussing good or bad designs. It is for discussing good, or bad implementations.

Your question clearly requests a design review, and not a review of the style and formatting of the interfaces you present. As a result, a review of those things would be of low value to you, and probably not appreciated.

If you had presented those interfaces, and requested a style review, I suspect that your question would be on topic, and a review would possibly look like:

---

interface ITaksManager : IDisposable
{
    void BeginInvoke(params Action[] tasks);
    event Action<Result> Completed;
}

Really, you should spell it "ITaskManager", and not "ITaksManager". Otherwise your indewntation is good, and the variable names are decent.

Obviously, this is not what you are seeking, so, based on what you have presented, the question is off-topic.

Answer 2

It's often said that "We don't review design, we review code." In fact, there's a meta question asking for clarification of when reviewing design is on topic and when it is not. The accepted answer there states

So I would say that if the question contains code, and the asker wants the design of that code reviewed, there's absolutely nothing wrong with that, but if the asker wants something that is not code reviewed, it's off topic.

With that in mind, I am going to change my earlier position on this and challenge the ruling on this one. An interface is code and the code in question is working code. An interface is a contract, so by nature, much of any review of an interface will be about design, but not necessarily all of it.

I've been told before, and I agree that

Just because we're not sure on how to answer it doesn't mean it's off-topic.

Which I would rephrase as "Just because we don't know how to review it (yet), doesn't make it off topic."

Now, with all that said, I'm not sure that questions like this will receive many good answers, and it may be a question better suited for programmers, but we don't know that. More importantly, I see nothing in our currently accepted rules that makes this question off topic. We have allowed other interface only questions. Here is an example of a well received Q & A on an interface. However, I think it makes a better question to include an implementation as well.

Answer 3

On Code Review, we require working code. That means:

• It has to accomplish a task
• … correctly, to the best of your knowledge.
• Omitting some portions of the code may be acceptable, but you can't put placeholder comments for core functionality.

In your specific case, all you have presented is interfaces, which are nowhere near runnable code. Interface design questions may be asked on Programmers.

Answer 4

I wasn't happy with this design, because it forced me to collect all the actions in one place, and because it is not very loop-friendly.

Does the interface really force you to collect all the actions in one place or do you not understand how to do it differently? This is where you should show us what you did to implement this code to show us why you think it forces you to collect all the actions in one place, someone else might be able to show you a better way of implementing the simple Interface that you have.

---

Does it make sense, that token has Completed event?

When is the Token's Completed event called in the implementation of the interface, how is it used? what is the actual method that is going to be called?

An interface defines what a class needs to follow certain rules, and doesn't actually perform logic.

an interface only says that the implementing class needs to create the event Action<Result> Completed it doesn't say what it does or how it works

---

[point #2] to be able to group tasks together in chunks. The general use case is: i pass multiple Actions to the manager, and if it is busy peforming previous tasks, then those new tasks are dropped. Just to give you an idea on why I need this.

An Interface cannot perform logic on it's own, it needs to be implemented in a class where each of the interface components are created and implemented.

none of what you described in point 2 can be done by an interface alone, the interface is really a Template for classes, which is considered design, and that is a totally different animal than code that is review-able.

---

The Point that I am making here is that you haven't given anything in the question that is review-able by the terms of Code Review

Answer 5

Let's take another example :

I want to review some Spring Data Repository method's I've created.

Spring data is fully working with just creating interfaces because in the back the code is generated.

So that question is also off topic while it do what it have to do?

I stand with @ckuhn203 that it is a good question.

• Interfaces is a contract that you could write in various ways.
  
• Interfaces are code.
• Setting up a decent interface before you lose valuable time is also refactoring.

So a question of reviewing design at the hand of a interface is for me legit. (As long the interface compiles!)

Answer 6

I want to state my opinion.

I thought the question you should ask yourself, when judging, if the code is "incomplete", is this:

• Is the amount of code provided enough to answer the question?

If the answer is "yes", then you should not dismiss the question, be it a single LINQ query, single interface, or whatever based on incompleteness (you can dismiss it for other reason, obviously: if the question itself is off-topic, for example). For example. this should be considered a perfectly valid question with a very useful answer.

In my specific case, I do not see how adding 500 lines of implementation will help you answer the questions I asked. If I wanted to ask other questions about other parts of my code (such as "hey, what do you think about my implementation? Can it be improved?") I would add the relevant code. But I didn't want to, not at this point anyway.

Either way, I would like the FAQ to contain a guideline which will help me and others to tell which code is "complete" and which is not. Because right now it is too subjective in my opinion.

Answer 7

I've previously stated that I believe that requests to review just interfaces are off-topic. I'd like to add a second answer explaining why I think they should be off-topic.

A key ingredient to the success of Code Review is our working-code requirement. It brings concrete benefits to the community:

1. It serves as a barrier to entry, preventing "gimmetehcodez" questions, helping to ensure quality.
2. Because of that minimum quality guarantee, we have a pool of members who are willing to regularly help review code.
3. Working code unambiguously specifie the behaviour of the program, removing a lot of guesswork about the author's intent.
4. The code focuses the discussion. Any answers have to suggest improvements, so in theory their quality should be at least as high as the question. Concrete questions yield concrete answers.
5. The code reveals a lot about the author, such as skill level and thought processes.
6. Even when the code in the question accomplishes its goal poorly (such as in time-limit-exceeded questions), reviewers are willing to do a deep technical dive, as a kind of reciprocity for the questioner's contribution.
7. Ultimately, the working-code rule is the reason Code Review has MathJax, while Stack Overflow and Programmers don't. Our reviewers are happy to help explain things at that level of detail!

Allowing just interfaces to be reviewed would fundamentally weaken that rule.

Here is a hypothetical exchange if we allowed interface-only reviews:

Questioner: Here is my implementation of an AJAX widget to frobnicate a whatzit.

Commenters: Welcome to Code Review! Your frobnicator doesn't actually work. Unfortunately, we only review working code here. Voting to close.

Questioner: Never mind about the code then. How about if you just review the naming and the interfaces instead, to let me know if I'm on the right track? Edits out most of the code

Even though good interface review questions might be possible, I fear that allowing any interface-only questions would irreparably damage the community. I think that the current requirement to present code that successfully accomplishes the stated task is a fundamental characteristic of Code Review, and should continue to be strictly upheld.

If you have a question about interfaces, include a working implementation and we will be glad to review it. Sorry if it means you might waste some time going down the wrong path, but that is just how it has to be.