# Questions about interfaces, protocols, and APIs

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.

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!

• Then they ought to be tagged with naming and interface? – Mathieu Guindon Aug 17 '14 at 21:20
• Sure, and definitely not with [performance] or [optimization] etc. – nhgrif Aug 20 '14 at 23:41

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.

• I don't see how this answer is compatible with this question. Design questions are on-topic if there is an existing design already. If the design is embedded in code, it's reviewable. – Simon Forsberg Aug 18 '14 at 16:19
• @SimonAndréForsberg because the design isn't embedded. It's just been translated. You put up only an interface, you might as well have used a tool to generate it from an UML diagram. – Pimgd Aug 18 '14 at 16:42
• I think comments like "I see you have method A and method B in your interface, might it make sense to also include something like method C which is sort of related to those two." can also contribute to a good review of an interface/API. Yes, the asker is reviewing something not yet written, but he's reviewing the fact that it's not yet written, and we see this regularly with Code Reviews of working code. – nhgrif Aug 18 '14 at 21:17
• Also, a direct comment on whether you think this question should be open or closed would be appreciated given I used it as an example in the question: codereview.stackexchange.com/questions/46194/… If interface-only questions are by rule off-topic, why does this remain open? – nhgrif Aug 18 '14 at 21:26
• @nhgrif you're being overly impatient here. Let everyone have their say and lets cement it into the faq/help center. It can still be locked/closed/whateverd then – Vogel612 Aug 18 '14 at 22:56
• @Vogel612 Yes, but I specifically asked about this question in my question. Both rolfl and 200_success have spoke out against interface-only questions on Meta, yet neither will comment directly on this question. I'm fine with them leaving it open while the discussion is pending, but I'd at least like a direct comment from the moderators who are choosing to leave it open in spite of their own meta comments suggesting questions like these belong closed. – nhgrif Aug 18 '14 at 23:01
• @nhgrif Imo that's pretty obvious. They don't want to override a possible community majority by creating "hard facts" and thereby induce discontent in the community. There's no real need to comment that. But that's just my opinion. For theirs you'd need to ask them. If it itches you that much =) – Vogel612 Aug 18 '14 at 23:06
• Again, I understand leaving it open while the community verdict is out. My comment is mostly asking rolfl to comment on whether he feels it is fine as open or whether he thinks it should be closed. To me, that question stands as an example of a very good interface/API question. It's a stellar test case. If you think interface/API only questions are off-topic, then you should be able to state that the question I'm pointing to should be closed. – nhgrif Aug 18 '14 at 23:09
• @nhgrif ... my current opinion is that, if it was asked again, it should be closed. As it is, I would historical-lock it. My current opinion is not settled, though. Also, my opinion does not count as much as the general consensus – rolfl Aug 18 '14 at 23:14
• I understand your last point. I just felt as a moderator with the power to close it that it was important for your opinion on this question that could've been closed but wasn't should be a little important. – nhgrif Aug 18 '14 at 23:15

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:

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

• I only see naming and design answers in the linked questions (and extensions thereof, such as conventions)... – Pimgd Aug 18 '14 at 12:20
• @Pimgd, So? What's your point? I never said interface only questions make for good questions. What I'm saying is that we currently have no rule that makes them off-topic. – RubberDuck Aug 18 '14 at 12:27
• I'm solidifying my point that interface questions boil down to design questions, which are off-topic according to the help center. – Pimgd Aug 18 '14 at 12:33
• It has been determined already that reviewing design is ok so long as it is part of the code review. In other words, the question must contain code. – RubberDuck Aug 18 '14 at 12:38
• I agree with that point. I do not see code in the linked questions. All I see is interfaces which could just as well been generated from an UML diagram. – Pimgd Aug 18 '14 at 12:50
• Ok, so you're argument is that interfaces are not real code then? What else would you call it? If I make a syntax error, does the compiler not complain? – RubberDuck Aug 18 '14 at 12:53
• asdfkljasdflkadjsf is not real code, yet the compiler will give you some syntax error – Pimgd Aug 18 '14 at 13:02
• But there's no intent behind that. You're stretching. That's a straw man fallacy. – RubberDuck Aug 18 '14 at 13:04
• – Pimgd Aug 18 '14 at 13:04

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

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.

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.

• There's a different between "not doing anything" and not being executable code. – RubberDuck Aug 18 '14 at 12:29
• @ckuhn203 Which is? – Pimgd Aug 18 '14 at 12:32
• An interface creates a contract that is then enforced by the compiler. Is that "doing nothing"? – RubberDuck Aug 18 '14 at 12:34
• @ckuhn203 ... yes? It's not verb-ing anything. Not calculating, sorting, altering, reading, writing, saving, printing, ... crashing?... so it's... pretty much doing nothing. – Pimgd Aug 18 '14 at 12:53
• have you read this? The term "working" code was added to the help center in response to broken code. I maintain that you're using the wrong definition of "work". – RubberDuck Aug 18 '14 at 12:56
• What about an API with binary for the library linked to? This unquestionably does something, but it is the interface I want reviewed – nhgrif Aug 18 '14 at 13:05
• @nhgrif Then it'd still be off-topic; adding "I have a binary" doesn't really change the question. More specifically, the code in the question still does nothing. – Pimgd Aug 18 '14 at 13:19
• It enables someone to user the binary. – nhgrif Aug 18 '14 at 14:27