last day (60 days later) » 
13:00 - 15:0015:00 - 20:00

1:04 PM
A: Questions about interfaces, protocols, and APIs

ckuhn203Let's look at our six magic questions. Is code included directly in my question? (See Make sure you include your code in your question below.) Am I an owner or maintainer of the code? Is it actual code from a project rather than pseudo-code or example code? Do I want the code to be ...

I only see naming and design answers in the linked questions (and extensions thereof, such as conventions)...
@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.
I'm solidifying my point that interface questions boil down to design questions, which are off-topic according to the help center.
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.
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.
1:04 PM
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?
asdfkljasdflkadjsf is not real code, yet the compiler will give you some syntax error
But there's no intent behind that. You're stretching. That's a straw man fallacy.
Could be....
Ok. I took a deep breath.
I would legitimately like you to convince me that an interface is not real code.
That it's somehow psuedo or example code.
The thing is I would see it as on-topic if there was an implementation next to it
I believe that a question containing just interfaces contains example code,
because the purpose of the code is only to showcase the design, which is the thing the question is actually asking about.
One can generate this example code by having an UML version of their design and having it automatically generate the code for that.
Though that's a bit of a strawman because GUI code can be generated too =/
It's primarily because detracting the code from the question and replacing it with a class diagram doesn't make you worser off
all that you lose is the comments
and comments aren't code
If they were, //and then array is sorted in O(1) would solve a lot of problems
1:20 PM
Lemme spin it around... is there any question you can ask about just interfaces that leads to something that's not about design?
If not, then how is the design described by interfaces different from a class diagram?
(Or plain english)?
@ckuhn203 poink
Well, I would refer to nhgrif's answer to that question. And Donald's answer to when design review is on topic.
It has already been determined that design review and API review are on topic, so although, there's not much difference, it's moot, because it's on topic. Mostly because the question contains code.
It's code, but it's a carbon copy of a diagram.
(Because it's an interface).
Which is a fair point.
The thing is given the following situation
Consumer - Interface - Supplier
I'd be happy to review a question containing all 3, or just the interface and 1 side
even only the consumer or the supplier would be okay
But just the interface... that's... only design.
But design itself is not off topic. No where does it say that design is off topic.
1:26 PM
On topic: Best practices and design pattern usage
Off topic: Higher-level architecture and design of software systems
(and even then I'd argue that there's no such thing as a design pattern that consists of just an interface - it'd still have to be used)
Ok, but then how does this fit in, if we've determined interfaces are indeed real code.…
I don't see how that determines interface is real code.
The question describes a working application and the answer seems to say that aside from general review, pointing out things with the design of the code is welcome too.
19 mins ago, by Pimgd
Though that's a bit of a strawman because GUI code can be generated too =/
We're straying.
How so?
The core of your argument is that Interfaces are example code, yet we've not determined if they are.
1:31 PM
It's example code, being an example of an actual implementation
heck, that's what interfaces are for: "this is what an implementation would look like"
No. That's not what interfaces are for. It's for creating a contract.
Is there anything here or here that makes you think it's example code?
"one that is representative of all of a group or type" comes close
I was just reading that.
My own words.....
wtf is alfred though
This is alfred.
1:35 PM
Looks like a bob clone.
oh well.
There's a bunch of comments applicable
An example is a piece of code that has had it's complexity stripped away.
It was an attempt to limit the scope of the review.
those two.
note that I'm thinking about cyclomatic complexity here
but interface naturally hides how stuff is done
and when I'd ask the question "but how is this interface used?" then I ran into a limit
(I'd need to ask that to be able to really give a review)
Additionally, pulling from the other question
It's not possible to address higher issues (what do you even need this interface for?)
cause ... there's only the interface.
You don't know the implementation or the usage
Hmmm..... I don't like it, but you seem to be correct. Interfaces seem to fall into the definition of example code.
now time to take stabs at my own argument
you could add many many context describing the implementations and usage
like this is a SortStrategy
Which argument? Your answer, or the assertion that it's example code?
and it has functions to sort stuff ascending, descending, based on some comparison function...
if you tack on enough context is it still example code?
@Pimgd I would say no.
1:42 PM
(I have a feeling that if your question contains more meaning in words than in code something else went wrong)
I might even argue that that context may not even be necessary in some cases.
I should explain that said context is just ... words
A good interface will make those things readily apparent. A bad one will cause confusion, and would be things to mention in review.
but then what
What do you mean?
1:45 PM
also good/bad interface doesn't matter, really crappy code that works is still subject for review
Even if your compiler is spewing 5 warnings per line
A good or bad interface is subject to review. I've had my poor API's mentioned on a few occasions.
So, a crappy API is on topic.
Just as much as crappy code itself.
yeah but why
> 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!!!
That's why.
so usage?
1:48 PM
Then ... your interface should be coupled with usage code?
Example usage code?
If I write a clunky interface, it's going to be hard to use.
I think yes, example or real implementation should be included to make it a good question.
But it's not necessary to be on topic.
I'm still not 100% at ease with calling an interface "example code".
It's example code if you're using it as a way to describe your design
Maybe it's not example code if you're using it to describe your solution....mhmhmh
It's not describing the solution, it's an integral part of the solution.
1:51 PM
why do I only get to see a part
Perhaps because the implementation isn't written yet.
and neither is the usage?
I would definitely prefer to think I have the contract right prior to writiing the implementation.
Usage would be the implementation.
User - interface - implementer
Usage is things like in a for loop
1:54 PM
well you have an API right
it uh
I dunno, it sorts a list
if you just put the interface then how do I know how to use the interface?
By it's structure, naming, and documentation.
cause that seems the only way to test the usability of an interface
by trying to use it to solve some problem
I know just from looking at that .next() moves to the next item.
I don't think I agree.
Let's say I had to do this instead.
next(int steps)
I would call shenanigans, and say that's a poor interface.
next should always move one step, and otherwise should be named differently.
Meeting in 2. brb
maybe you get a list back?
next(int amount)
so "gimme the next 4"
ahhhhhhh, so these are legitimately reviewable things?
2:04 PM
If I had absolute authority I'd just demand that:
Provide problem
Provide solution interface
Provide solution usage
and then yay everything would be on topic
use case.
Interface is missing a use-case.
That's it.
You can show me interfaces all day but if you don't give me a use-case for it then reviewing it is hopeless
Lets go look at those questions you linked before
The first one is a tree node.
It has some use-case context
"My general target was to include a useful set of basic tree-related functions - obviously the bare minimum would be simply adding/removing/getting children, but I also felt as though automating potentially useful processes such as removing all children (pruneSubtree() - thinking recursive deletion) and removing a node from a given tree structure to leave a forest might help make future tasks easier."
but I'm lacking the real use-case. (What's it for?)
I'd leave a comment "What's the goal of your interface?"
Particularily since damn, treenodes
why not built-ins?
the second question is about...
a data ... layer?
That's off topic.
There's no usage, no indication what's it for, why you'd need it at all...
close reason would be a lack of context
2:33 PM
@Pimgd question: how would you make it on-topic then? (my question that is)
The second question can be made on-topic by adding a problem definition and a use case. That is, why they did what they did and how it would be used.
In doing so, the functionality (via the how) becomes clear, and it becomes possible to review the solution (via the why).
But DataLayer defines the use-case already
My application needs to fetch data.
▲▲ that is a whole use-case IMO
How that data is structured is primarily irrelevant.
It's just necessary to know that it's there.
Additionally, reviewing design architecture is off-topic. Reviewing design pattern implementation is on topic. The interface alone is not a design pattern, it's the combination of interface and usage thereof that makes a design pattern
So you want to say that an interface is not a design pattern?
A single interface is not
multiple interfaces are not
2:38 PM
where's the but?
but if you added usage it would be
@Pimgd Where's teh difference?
room topic changed to Discussion about Code Review and whether Interfaces are on-topic: Imported from a comment discussion on… [discussion] [scope]
how does usage make questions about an interface on-topic if interfaces are off-topic?
usage is always call methods of the interface
much wow ;)
room topic changed to Code Review - Discussion about whether Interfaces are on-topic: Imported from a comment discussion on… [discussion] [scope]
2:39 PM
hi @rolfl btw ;)
Because the usage has to describe how to use the interface to satisfy the use case
that is, how do you use the interface to retrieve data for the application?
(for that specific example)
@Pimgd IMO, if an existing design exists already (within the code), it can be reviewed.
the interface intrinsically describes how to use itself to satisfy the use-case
The logic is as follows
and fwiw, why would you need the implementation to review the interface?
you're reviewing the implementation then
2:41 PM
If you had an application in two parts... something that did stuff with data, something that retrieved the data and the interface between them, it would be on topic
If you only had the retrieval with the interface to describe the output format, it'd be on topic
if you only had the display and the interface, it'd be on topic.
so you're saying because I didn't show you a usage of the interface, it doesn't exist?
A comment that "the interface would be better if it would return a list instead of having to ask for each item individually" is valid in all those 3 cases.
How about this example?
Q: Is the public interface easy to use and the documentation understandable? Are the unit tests well-written?

kris741I have a year or so of experience in developing in Java. I submitted the solution for this task, but never got the feedback that was promised. Since I still would like to get a feedback on my solution, I figured that here I will find skilled developers who wish to help me and others who may have ...

I think that having some code helps.
But a sole interface would be offtopic because it's lacking context. it's not known what problem it solves and how it solves the problem and why it even needs to solve the problem
sorry but how is not clear what problem is solved in my question?
2:44 PM
@200_success Helps, yes. Necessary to make it on-topic, no.
said question has
A problem description
an interface
and usage (via unit-test)
thus it becomes easy to see if it's easy to use the interface (the question asked)
@Pimgd For questions that are lacking context, no matter what the question is about, there is already a close reason: unclear what you are asking
my question has:
a problem description (simply by using the title)
an interface (more than one at that)
and usage (inferrable by use-case and given information it is a JEE app)
maybe I just lack the knowledge?
maybe ;)
2:46 PM
How does that even work in retrieving the things
It has been said that an API needs two independent implementations to validate it. Asking the author to supply one seems reasonable.
@200_success so you'd rather have me "dump" one of my implementations?
@200_success Has Vogel's interface-only question caused any harm at all to Code Review?
@SimonAndréForsberg Reasoning?
@SimonAndréForsberg beside the point ...
2:47 PM
@200_success There's a difference between "helps" and "required"/"necessary to make it on-topic"
@Pimgd you know, the use-case of these interfaces is quite simple:
We are debating whether it should be on or off topic, so we have to consider benefits and harms.
@200_success And so far, I don't see any harms.
Then we revise our definition of "working code" if necessary
 List<Customer> myList;
 ICustomerService customerService;
 public CustomerListController() {
      myList = customerService.getAll();
now what does that change??
2:50 PM
it clarifies the usage of the interface
@200_success Hasn't that one always been a Gray Area of Code Review (TM)? Have we ever had a clear definition of "working code"?
it also shows what you'd expect of it
@Pimgd but that is clear by the interface itself!
We probably each thought that our own definition was the one.
the interface defines the usage
2:51 PM
Maybe if your interface consists of 1 method.
@200_success probably.
@Pimgd and what if it consists of 20?
then your problem is a combination of methods
the interface still defines the usage.
no not really.
and solving the problem is done via non-trivial usage of the interface
2:52 PM
it's no different if I have a class with 20 methods.
@Pimgd but that's nowhere near given when you consider that I gave following context:
> Just for a small info, I am currently building a CRM as "training JEE application"
To me, "working code" is code that compiles and does what it is supposed to do. I see no reason why an interface cannot be a part of that. Sure, an interface doesn't execute code (unless we're talking Java 8 default methods), but an interface still has an important role in programming, and it can be reviewed.
and the wording DataLayer interfaces
Let's define it after we have considered harms and benefits.
@SimonAndréForsberg the point is, is "what an interface is supposed to do" and "what code is supposed to do" the same?
I have to go soon
but I know that interface + problem definition + usage will make for a good question
and an on-topic one
I don't know if a sole interface will do that
2:55 PM
Sure If I had just dumped my interfaces it would have been hard to infer usage.
I also don't know whether usage should be in code
@Pimgd All questions need a "problem definition"
oh, that helps
@SimonAndréForsberg and code is something like a "problem definition"
because if the code doesn't solve the problem, it's not working.
@SimonAndréForsberg @200_success I could not find a clear definition of "Working code" on meta.
2:56 PM
recall that queen code from a couple hours ago
@Vogel612 Well, yes, but questions still should describe what the code is doing.
working code that they wanted performance boosts for
it was terribly unreadable
so the problem definition is not self-justifying, but necessary for the working as designed off-topic reason.
and the problem wasn't even specifiied
@Pimgd give it a readability review and move on.
nobody expects you to optimize unreadable code...
2:57 PM
This is where "working code" was added to the off topic reasons, and it seems to address broken code.
that'd be hard to do; they're aiming for top performance
splitting things into different lines won't achieve that goal
anyway I have to go now, but I think I'll be reading this convo from phone with buswifi
also responding but slooowly.
Buses have WiFi? Wow.
13:00 - 15:0015:00 - 20:00

  last day (60 days later) »