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

Consider renaming API entry points to align with conventions, better convey purpose #47

Open
othermaciej opened this issue Aug 31, 2021 · 0 comments
Assignees

Comments

@othermaciej
Copy link

This is a few separate points about naming, they seemed better reported together, but I'd be willing to split the issue.

  1. setLoggedIn sounds like a setter that would take a boolean, but it's not. You could imagine just calling it logIn, but this method doesn't actually perform a login; it just reports or records that status. That would suggest names like:
  • reportLogin
  • recordLogin
  • userLoggedIn
  1. If a change like that is made, then it would make sense to also change setLoggedOut to reportLogout or recordLogout or the like.

  2. Boolean getters in the DOM aren't given names starting with is, as is the convention in some other APIs. More common is plain adjective names like cancelable or disabled or complete (examples taken from DOM and HTML specs). On top of that, getter methods, particularly ones that return a promise, or not usually named as if they were an attribute. Rather, they're named like imperative verbs. For example, Permissions API has a method query to get the permission status. HTML has methods like convertToBlob and createImageBitmap. File System Access has getDirectory, getFile, and requestPermission (in fairness, also a counterexample: isSameEntry, but this is a comparison function that takes a parameter, not an async pseudo-getter.)

Overall, I'd recommend a name like getLoginState or checkLoginState. In code using promises, this reads pretty clean:

navigator.checkLoginState().then(state -> doSomething(state))

Whereas this (IMO) seems a bit awkward if you read it out loud:

navigator.isLoggedIn().then(state -> doSomething(state))
  1. The methods should perhaps not be on window.navigator. The Navigator object is intended for info requests (and a few operations) that are truly global to the browser, affecting all sites/pages, rather than something scoped to a site. More local info/operations are generally put on another interface. For example, registration of custom elements is done via CustomElementRegistry, which is available as window.customElements, and this allows addition of new custom element definitions as well as retrieval of existing definitions. However, counterexample: Permissions API instead extends the Navigator object (as well as WorkerNavigator).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants