7
\$\begingroup\$

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?

\$\endgroup\$
10
\$\begingroup\$

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.

\$\endgroup\$
  • 1
    \$\begingroup\$ So, was that a yes or no? You spent most of the answer saying it's off topic only to point out flaws in the code??? \$\endgroup\$ – RubberDuck Aug 16 '14 at 10:26
  • 3
    \$\begingroup\$ @ckuhn203 - you're right, the last part of my answer could be considered to be confusing. I have re-structured it to make it clearer what I am trying to say. \$\endgroup\$ – rolfl Aug 16 '14 at 21:38
  • \$\begingroup\$ 2. I do no request "wants", i describe "have's" to give reader an idea on why interfaces look this way, and not that way. Questions are marked with question mark, and i thought it makes them easy enough to spot. For some reason you've missed them though. \$\endgroup\$ – Nikita B Aug 18 '14 at 5:40
  • \$\begingroup\$ 3. Those interfaces exist, and so does implementation. You advocate a presumption of guilt, where "you can't tell" = "i'm guilty". Which is considered a bad logic in most parts of civilized world :) \$\endgroup\$ – Nikita B Aug 18 '14 at 5:51
  • \$\begingroup\$ 1. Above all, interface is a contract. And this contract can certainly have bad namings, bad signatures, bad encapsulation, use bad practices and have all the other issues, which are subjects for code review (except for, probably, performance). \$\endgroup\$ – Nikita B Aug 18 '14 at 5:58
8
\$\begingroup\$

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.

\$\endgroup\$
4
\$\begingroup\$

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.

\$\endgroup\$
  • \$\begingroup\$ So any interface, impementation of which is unknown, is "broken" code by that definition? I find that really wierd. \$\endgroup\$ – Nikita B Aug 15 '14 at 8:25
  • \$\begingroup\$ Not really "broken", but "not working", or as the close reason calls it, "code not yet written". \$\endgroup\$ – 200_success Aug 15 '14 at 8:26
  • \$\begingroup\$ Hmm. So the questions i ask are ontopic, but the lack of code makes them offtopic? Am I right? \$\endgroup\$ – Nikita B Aug 15 '14 at 8:31
  • 2
    \$\begingroup\$ If you successfully implement one or both of your proposed interfaces, you can edit the question, and we could decide to reopen it. (Ideally, I'd also like to see a test case to demonstrate how it works.) \$\endgroup\$ – 200_success Aug 15 '14 at 8:35
  • 4
    \$\begingroup\$ Actually I have asked a question solely on interfaces. and I got 2 answers, where one was deleted again. Are you implying that questions about usage / design / code of interfaces are off-topic? \$\endgroup\$ – Vogel612 Aug 15 '14 at 10:01
  • 2
    \$\begingroup\$ FWIW I think that the question would get rejected on Software Engineering because it's not applicable for "all programmers", but "just for you" as seen in their help center. \$\endgroup\$ – Vogel612 Aug 15 '14 at 10:45
  • 1
    \$\begingroup\$ -1 Because there is no universal definition of what "working code" is \$\endgroup\$ – Simon Forsberg Aug 18 '14 at 15:56
1
\$\begingroup\$

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

\$\endgroup\$
  • \$\begingroup\$ Completed event is called when tasks are completed. I didn't think i have to explicetly state that. The fact that you did not understand that is actually a valid input. It means that my design is hard to understand. \$\endgroup\$ – Nikita B Aug 19 '14 at 5:42
  • \$\begingroup\$ Well, obviously, if method signature has array as its parameter, i have to first create an array, before calling a method. So yes such signatures force you to make sertain adaptations in the rest of your code. \$\endgroup\$ – Nikita B Aug 19 '14 at 5:43
  • \$\begingroup\$ I also have a feeling, that even though you criticize my question, you are somewhat making a review already. :) Being said, i think your answer is too specific. Can you add your opinion regarding interfaces in general: do you think they are offtopic or do you think that my specific question is just not good enough? \$\endgroup\$ – Nikita B Aug 19 '14 at 5:46
  • \$\begingroup\$ I don't think that interfaces are enough to review, they are templates, they can't be run by themselves, they don't accomplish the final product. \$\endgroup\$ – Malachi Aug 19 '14 at 12:22
1
\$\begingroup\$

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!)

\$\endgroup\$
  • \$\begingroup\$ Interfaces is a contract that you could write in various ways. which means it is going to be too broad. \$\endgroup\$ – Malachi Aug 18 '14 at 20:51
  • 1
    \$\begingroup\$ interfaces are black boxes just as your dependency's what you call. Setting up the doc correct you should know what it does, not how it's done. The design review is not about how it's done... \$\endgroup\$ – chillworld Aug 19 '14 at 4:48
0
\$\begingroup\$

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.

\$\endgroup\$
  • \$\begingroup\$ I think you might be missing the point: CR is not about asking questions, it's about reviewing code. Asking questions about your working code is okay, but questions about design are off-topic. \$\endgroup\$ – svick Aug 15 '14 at 9:53
  • 1
    \$\begingroup\$ I would just like to say that I agree with the sentiment of your opinion. But this particular question is a "whiteboard" kind of one that's better suited for programmers. \$\endgroup\$ – RubberDuck Aug 15 '14 at 9:55
  • \$\begingroup\$ "Because right now it's too subjective." - Remains to be seen. Also the "Beta-Phase" is meant for exactly that. Clarify the FAQ with unambiguous (well as far as possible) rules to follow ;) \$\endgroup\$ – Vogel612 Aug 15 '14 at 10:13
  • 1
    \$\begingroup\$ @svick, but I ask for review and ask review-related questions (which are considered on topic per FAQ). It just that i want you to review interfaces, and you want to review implementation. :) Which is a wierd situation. And I don't understand, why interfaces do not fit the definition of "code" (or "working code", or "complete code") and why they can't be reviewed. Maybe its because at my workplace i reviewed more interfaces than i can remember, and never had any issues with that. \$\endgroup\$ – Nikita B Aug 15 '14 at 10:33
-5
\$\begingroup\$

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 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.

\$\endgroup\$
  • 1
    \$\begingroup\$ Can FAQ explicitly state, that interface-only questions are offtopic then? Seeing as my question turned into quite a discussion, i think that current rules do not make it obvious enough. I'm not sure who is the right person to ask (I am sorry, if you are not the one :) ), as I am new to the meta forums. \$\endgroup\$ – Nikita B Aug 18 '14 at 9:15
  • \$\begingroup\$ While I don't agree that interface only questions should be off topic, if they are going to be, the help center should be updated to clarify. \$\endgroup\$ – RubberDuck Aug 18 '14 at 10:38
  • 1
    \$\begingroup\$ Do you intend to close this question then? codereview.stackexchange.com/questions/46194/… \$\endgroup\$ – nhgrif Aug 18 '14 at 11:21
  • 5
    \$\begingroup\$ Reading through your numbered list, I still don't see why interface-only questions need to be off-topic. A question that provides only the interface and asks for an implementation is off-topic as it is asking about code not yet written. However, any question that asks about something it did not provide is ALREADY off topic for this reason. Meanwhile, there's plenty to discuss about an interface without discussing how someone would implement a class with that interface. \$\endgroup\$ – nhgrif Aug 18 '14 at 11:23
  • 2
    \$\begingroup\$ Your hypothetical exchange is not very realistic. I strongly doubt that would happen here. If a questioner has a problem with making things work, naming and interfaces is probably the least of their concerns. \$\endgroup\$ – Simon Forsberg Aug 18 '14 at 12:45

You must log in to answer this question.

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