Questions about interfaces, protocols, and APIs

Question

Are questions about interfaces/protocols and APIs on-topic for Code Review?

And when I say "protocol", I mean this in the Objective-C/Swift (and potentially other languages) version of the word, which is basically the same as a Java interface.

There is this meta discussion: “Code not yet written” clarification: Are unimplemented interfaces on- or off-topic?, to which two moderators posted answers basically agreeing that the specific question which prompted that meta question is off-topic.

However, there exists this meta discussion: Are questions about public interface (API) on topic? which suggests that questions about APIs would be on-topic based on the existing accepted and highest upvoted answer.

I understand that APIs and interfaces are slightly different, but they're similar enough that I don't understand why a distinction would be drawn between the two (in terms of whether they're on-topic or not).

Moreover, there exists this seemingly very good question: DataLayer Interfaces Genericized, which is purely about interfaces, something which the moderators have suggested would be off-topic, yet the question has 10 upvotes, and an accepted answer with 7 upvotes. Moreover, it has 0 votes to close, nevermind the close action of a moderator.

Answer 1

Some time ago, I remember having discussion in chat (a discussion which should have been on the meta... which is why this is going on the meta now) about how much code a question has to include in order to be reviewable. Given that how we name our classes, methods, functions, and variables is such an important aspect and a large portion of reviews are spent on critiquing naming alone, an answer with nothing more than the name of a class has "enough reviewable code". Having actual executable code isn't actually a requirement for meeting some "enough reviewable code" criteria. I also made the point that "enough reviewable code" is not the only criteria by which we can determine whether a question is on-topic or not.

---

One of the things we spend a lot of time focusing on in reviews is the general readability of our code. We do this not because it makes the code perform better or use less memory, we do this because humans will read our source code several times more frequently than a computer will. It is important for humans to discern what's going on with the code.

In most cases, the focus on our review is, how readable is this to a maintainer of the code? After all, that's the human who looks at our code the most, right? Anyone involved in the upkeep and maintenance of our source code, correct?

But what about interfaces and APIs? While a maintainer looks at these things, a large group of other humans will look at these far more frequently. These are the end-user developers. It is arguably MORE important that your interfaces and APIs are very readable and contain methods which describe exactly what they do from name alone so that that developer may write readable code because he has no control over the method names you picked in your interface or API!!!

These things are highly worth of a good Code Review so that some programmer in the future perhaps doesn't post some source code that makes use of a library with cryptic unintelligible method names that he can not change!

Answer 2

Interface-only questions are off topic. This is why:

1. Interfaces/Protocols define the interaction between two components. They describe a common mechanism for two otherwise independent 'systems' to communicate with each other. As a result:

   • the primary purpose of an interface is not to 'do' things, but to define a communication system
   • an interface can be 'broken' in only three ways:
     1. it is syntactically broken (it does not compile) - in which case it is off-topic
     2. it has bad style - in which case, it can be reviewed, and improved - which would be on-topic for Code Review
     3. the design the interface represents is bad - this would be off-topic on Code Review because design-related answers are too broad for here, and are on-topic on Programmers.se

   Note that I indicate that the style of an interface can be reviewed, but, given that the entire purpose of an interface is to declare a protocol, and that reviewing protocols is off-topic on Code Review, saying that the style is reviewable, but the functionality is not, is like saying you can review the style of a C or Java program, but not comment on the algorithm, or functionality.

   Reviews of the core purpose of interfaces (design and protocol) are off-topic, it follows that any answer that does not address the core purpose of the interface would be a low-value answer.

   Design-related questions (even if the design is expressed as an interface) are off-topic.

2. Interfaces are assumed to be immutable. Interfaces in general are not easy to change because it requires the change to be simultaneously applied to all implementing systems, as well as all 'client' systems. As a consequence, an interface, by definition is not self contained. It is not possible to suggest changes to the interface unless all the affected code is also available for review. A code review cannot be good unless it makes suggestions which are meaningful.

   If the question supplies an interface only, then then it can only be considered to be example code, because the current implementing/interacting code does not matter, is meaningless, and has no value to the asker in the context of the question. They are looking for a design review, not a code review. They may as well draw a picture/flow-chart instead of the interface (in fact, that would probably be better....).

3. Code reviews can suggest that the design is broken, or suboptimal, but, that is an observation that is derived from the code, not from the design. It is OK, on code review, to suggest the code could be improved if the design was different, a design-only review would be a low-quality answer.

   It follows that feedback on the design, on Code Review, follows an implementation review, not a design review.

---

But

I may be suggested though, that if a question provides an interface only, and specifically requests:

• this is my current proposed interface
• are the method names good, spelling good, documentation good, any style issues?
• once this interface is right, I will implement it properly

In other words, if the asker specifically asks for a style review, and specifically does not want a design review, then the question would be on-topic.

That may be the case, but the code is still essentially example code, and the naming, spelling, and structure could be reviewed on the implementation instead. The implementation is not example code.

---

So, Interface-only questions are off-topic.

Answer 3

Let's look at our six magic questions.

1. Is code included directly in my question? (See Make sure you include your code in your question below.)
2. Am I an owner or maintainer of the code?
3. Is it actual code from a project rather than pseudo-code or example code?
4. Do I want the code to be good code? (i.e. not code-golfing, obfuscation, or similar)
5. To the best of my knowledge, does the code work?
6. Do I want feedback about any or all facets of the code?

For the sake of argument, we can assume that the code is embedded in the question, OP maintains the code, wants it to be good code, and wants feedback on all facets of the code.

That leaves us with just two things to ponder on.

• Is it actual code from a project rather than pseudo-code or example code?
• To the best of my knowledge, does the code work?

The prior is often referred to as "real code", so is an Interface real code? Well, it's certainly not pseudo-code. Let's also assume, again for the sake of argument, that the code in question does not contain classes or methods named Foo, Bar, and the like. Therefore, not being example code. That leaves just one last test to pass.

Does this code work?

To determine if code works or not, first we have to understand what it means "to work". I could not find a meta post clearly defining what working code is, so I'll refer to Meriam-Webster. Irrelevant definitions omitted.

Work intransitive verb 1 b : to perform or carry through a task requiring sustained effort or continuous repeated operations 2 : to function or operate according to plan or design 4 : to produce a desired effect or result : succeed

Definition 1b is the only place an Interface fails to meet the definition of "working code". It does indeed meet the definition of "to function or operate according to plan" and to "produce a desired effect". Which, I would argue, is our intent by asserting that code must "work" to be posted as a question here. What we really mean is that the code must be functional. It must compile and produce the intended results. An Interface creates a contract that implementing classes must abide by. They do not execute code, but that does not make them broken. That's what we really care about here. Is the code broken? No, interfaces are (obviously) not broken code by mere virtue of their nature. By that measure and logic, Interface only questions are indeed on topic.

Furthermore, Interface questions have been well received in the past. Some examples:

• Interface for a tree node in Qt
• DataLayer Interfaces Genericized

Update: I am leaving this here, because I think it is important to the discussion to note that it is not the question of "working code" that makes interface only questions off-topic. It seems that I was mistaken to assert that Interfaces are not to be considered example code. This quote from rofl's answer convinced me of my logic error.

If the question supplies an interface only, then then it can only be considered to be example code, because the current implementing/interacting code does not matter, is meaningless, and has no value to the asker in the context of the question. They are looking for a design review, not a code review. They may as well draw a picture/flow-chart instead of the interface (in fact, that would probably be better....).

Answer 4

Are questions about interfaces/protocols and APIs on-topic?

Yes. But that does not mean that the question itself is on-topic. There are still other factors to consider, such as: Is there enough context in the question? Is it clear how these interfaces will be used?

I see no reason whatsoever to create a rule that says "Interface-only questions are off-topic. Period." Each question needs to be looked at individually.

For example, have Code Review suffered from having considered this question as on-topic? Or this question? I don't think so. Likewise, if more questions with high-quality like this appear, I see no reason that they should be closed for being off-topic.

---

Are questions about interfaces/protocols and APIs on-topic?

Sometimes.

Are questions about interfaces/protocols and APIs off-topic?

Sometimes.

---

I don't think we need a rule stating that interface questions are on-topic or off-topic. It all depends on the rest of the question.

I'm stating that questions about interfaces can be on-topic.

What does it take for a question about interfaces to be on-topic?

• Good description of the purpose of the interface
• Sufficient amount of code to answer the question
• Clear question

If you consider an interface-only question off-topic, then it is more likely because it is unclear what you are asking.

Answer 5

I'd say no.

Applying ckuhn203's answer, but I disagree with the last point; it doesn't actually do anything, so it's not working code for me.

It's more like a bunch of structs.

And what can you ask about a bunch of structs and interfaces?

Well, whether you've named them right, of course... but more importantly, is the design of these interfaces/classes correct? That's the sole question hiding behind a couple class and interface names with a couple variables.

So there's two points to review: naming and design. Naming is on-topic, but design is off-topic (when they're the sole focus). ... So now what?

Well, since the interfaces don't DO anything, there's no implementation to verify how they're supposed to work. All you have to go by is the plain English and the naming to discern functionality. And since we'll want to reduce the dependency on the English, we'll start altering the design to document itself via proper naming. And that'd be off-topic again.

Questions about interfaces lead to reviews focused about naming and design. However, without any functionality, naming IS design. Thus, such questions are off-topic.