12
\$\begingroup\$

I'm writing some library code (ex. jQuery plugins, Django apps) that is meant to be used by other people as building blocks for larger applications. Often I don't see much need for others peer-reviewing my code, but it would be great to get people's opinions on its API (the public interface to each component), since the earlier I fine-tune them (preferably long before the code is released) the more opportunities I have to make changes. After the code is released, changing the API without breaking legacy code is much harder, specially if my libraries have many users at this point.

The objective of these questions would include, among others: the classes/methods/etc names are good, descriptive and self-documenting? The number/order/types of the parameters are intuitive/follows the platform's conventions? Are there useful operations that are missing, or are ankward to use in the current form? Are there doubts about whether or not a function would work with certain corner-case arguments?

My question is whether or not this kind of question is on topic for this site. Or if there is any other Stack Exchange site where I could ask about this. API design may be a bit more subjective than most other facets of code (security, performance, correctness), but not a lot, about the same level as "best practices and design pattern usage".

And if on-topic, may I ask these questions without including the whole (or any) code? I mean, implementation code, examples of usage would be obviously needed. Not that having the rest of the code reviewed would be bad, just that the question might get too long with it (and the focus is on the code as a black box - exactly how most users will see it).

\$\endgroup\$
7
\$\begingroup\$

Are questions about public interface (API) on topic?

Yes! If they are from a specific working piece of code.

Quoting from the relevant part of the FAQ:

If you are looking for feedback on a specific working piece of code from your project in the following areas…

  • Best practices and design pattern usage

then you are in the right place!

It also answer yes to all the on-topic questions:

  1. Does my question contain code? (Please include the code in the question, not a link to it)
  2. Did I write that code?
  3. Is actual code from a project rather then pseudo-code or example code?
  4. To the best of your knowledge, does the code work?
  5. Do you want feedback about any or all facets of the code?

Ultimatly, to be off-topic should not be a question "about a particular piece of code and" but "a generally applicable question about ...".

Well, yours is clearly about a particular piece of code.

And if on-topic, may I ask these questions without including the whole (or any) code?

As I just quoted from the faq, to be on-topic it needs the code.

It also says that it should be working. I'm not sure how to interpret this point, I don't think it's necesarry to have a compiling piece of code, I'd say that a bunch of API declaration is "working" if it's coherent and consistent (in poor words: it looks ok).

As I said I may be wrong about this "working" interpretation, maybe some one else will give you some better insight about this, or you could just try and if people complain about it it means that you'll have to post all the code.

\$\endgroup\$
  • \$\begingroup\$ I had an API question earlier. I actually had all of it implemented, but I wanted feedback on the interface, not the implementation, so I only included that. Do you think that this is an on-topic question? \$\endgroup\$ – Tamás Szelei Apr 10 '12 at 8:51
  • \$\begingroup\$ @afishwhoswimsaround: I don't see why it shouldn't. The "complaining" below is in regard of not providing enough information, but the question is on-topic. \$\endgroup\$ – Rik Poggi Apr 18 '12 at 8:08
  • \$\begingroup\$ Sir or Ms Answerer, if you'll allow me to resurrect this issue, I need a few clarifications before I can apply an upvote on both Q and A. On-topic #3 requires "actual code from a project"; there are multiple interpretations. If I write a library and ask about its API, the actual code of the library is not what I would like to submit for review. To evaluate the API requires human-language documentation ("pseudo-code"?) of its notable features and important use cases ("example code"?). Please tell me why it's different so I can dump all my libraries on CR. \$\endgroup\$ – sqykly Dec 31 '15 at 13:12
  • \$\begingroup\$ I'd say that a bunch of API declaration is "working" if it's coherent and consistent (in poor words: it looks ok). - isn't the whole point of Code Review to determine whether it looks OK or not? \$\endgroup\$ – Simon Forsberg Mar 30 '16 at 5:30
5
\$\begingroup\$

The FAQ says that the following is off-topic:

  • Higher-level architecture and design of software systems

Okay, that's not exactly the definition of API, but it's close enough, so rather go to http://programmers.stackexchange.com. I've had a look at their [api tag], and they do accept such questions.

\$\endgroup\$
  • 4
    \$\begingroup\$ I don't think API in this case refers to something high-level. As my second paragraph shows, it's dealing with smaller details to make the API more usable, not with deciding what goes to the API. Whether or not it's a good fit for this site, I doubt it would be in programmers: their FAQ says (shows) explicitly that the questions must be applicable to a wider audience (this site, in contrast, seems to be more "personalized" - correct me if I'm mistaken). But I'll take a closer look at it anyway, thanks for your feedback. \$\endgroup\$ – mgibsonbr Apr 3 '12 at 8:25
  • \$\begingroup\$ @mgibsonbr: I don't that such API question are off-topic here (as I said in my answer), but if you care to abstract a bit your API set, it will probably make them on-topic on programmers.se \$\endgroup\$ – Rik Poggi Apr 3 '12 at 17:28

You must log in to answer this question.

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