Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Define public API #1393

Open
markandrus opened this issue Apr 29, 2017 · 3 comments
Open

Define public API #1393

markandrus opened this issue Apr 29, 2017 · 3 comments

Comments

@markandrus
Copy link

Thank you all for this valuable resource. I was catching up on current practices with respect to "private" properties in JavaScript when I came upon the discussion in #490. It seems to me that the definition of public API used by this style guide is stricter than what SemVer describes. For example, the guide currently states that

Although a leading underscore is a common convention to mean “private”, in fact, these properties are fully public, and as such, are part of your public API contract.

So, as far as this guide is concerned, anything which is accessible in a JavaScript library constitutes its public API. On the other hand, SemVer describes public API differently:

  1. Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive.

I take this to mean that, as a library author, I am free to explicitly include and exclude properties from my public API, regardless of whether or not they are accessible in my JavaScript library.

So I propose that this guide define public API for itself and explain why it adheres to the definition that it does. I think this would inform developers evaluating the pros and cons of whether or not to adopt or reject a private convention in their projects.

@ljharb
Copy link
Collaborator

ljharb commented Apr 29, 2017

Public API is everything reachable and accessible at runtime, full stop.

semver.org's description is more pragmatic out of necessity, because the value of semver exists no matter how public API is defined. The reality is that if you cause any user anywhere to break, not matter how dumb the thing they're doing is, you made a breaking change; it's your fault; and you have a moral and ethical obligation to fix it.

Totally separately - "private" to most people has connotations that it is unreachable - not just that "it'd be really swell if you didn't interact with it". Our guide's stance on privacy is unrelated to the definition of "public API", because the word "private" carries connotations that transcend any given specification's definition.

@markandrus
Copy link
Author

Public API is everything reachable and accessible at runtime, full stop.

I think it would make sense to expand upon this position in some form in the guide. "Public API" is currently only mentioned in 22.4, but I think it could also inform future work on the Comments section. I know some projects prescribe that all exported API members should be documented, but I'm not sure the guide's current position.

@ljharb
Copy link
Collaborator

ljharb commented Apr 30, 2017

Documentation is a good thing, but I don't think it's always necessary to document all of the public API.

Adding a section to the guide about public API seems like a good idea.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants