(Pedantic) thoughts on naming conventions

[dflorey]

While migrating my app to the new modulized sdk I've been running into some name clashes, espcially for the doc() method that clashes with my "doc" variable in the callback. While this is of course just a minor annoyance I've been thinking about the naming conventions in the sdk a bit.
I'd prefer a consistent naming scheme like this (which would also reduce the number of clashes with variable names that I guess are widely used with the old sdk):
Using either full or abbreviated method names, so either
collection(...) document(...) onSnapshot(...) setDocument(...) etc.
or
col(...) doc(...) onSnap(...) setDoc(...)

I'd prefer the full names, as it is nicer to read and I guess it will also not affect the generated bundle size.
The "Common use case" would then be much nicer to read as

const docSnap = await getDoc(docRef); // <- Using docSnap as doc would clash with the imported method

would become

const doc = await getDocument(docRef)

etc.

A new SDK version is a great opportunity to start with fresh and consistent naming schemes, so even though it may be just a matter of taste I think it is worth to provide some feedback.

[merlinnot]

Agreed, it was always surprising for me that we have .collection and .doc. I'd prefer full names as well, especially that it looks more tidy when used alongside type definitions, which are all full names.

[mbleigh]

I vaguely remember our original conversations about this. We ended up here because "doc" is a universally recognized shorthand for "document" (no risk of confusion) and was also something that was going to end up getting typed a lot. "Collection" does not have a clear analogue -- "col" is a common abbreviation for "column" and "coll" doesn't really pop. "Snap" is reasonably clear for Snapshot, but it's not quite as universal.

Would folks feel better (as a counterproposal without any thought behind it) if Document were universally renamed to Doc for consistency of a single term?

[mbleigh]

Huh, I never thought of it before but you're right that onSnapshot makes it sound like a verb (a snapshot is happening). I think it would more accurately be onNewSnapshot, but yeah it's effectively onChange (although I think the reason that we don't call it that is because our event listeners also trigger immediately with the current value even if it hasn't changed).

Lots of subtlety here and it's definitely something that I think many of us are taking for granted, so thanks for the interesting discussion!

[dflorey]

Probably it is because I'm (relatively) new to firebase and I've used the "old" Datastore before. I've then been reading about the new datastore (aka firestore) and the docs are talking about "Documents" only:
https://firebase.google.com/docs/firestore/data-model
So it is not clear at first sight what a "snapshot" is - as this term is never introduced. It gets kind of clear how to use it though, but to me it would be more easy to understand if getDoc() aka getDocument() would just return a Document and onSnapshot() would be onDocument() or something along those lines...
Anyway, I think a few variable names in the new docs could be aligned to improve the readability (without changing any of the given mwthod/type names in the sdk itself)

[akauppi]

@mbleigh Hey - you mentioned Realtime Database!

Would it be too much to ask to consider calling that product realtime in the API? Having database is simply confusing, because also Firestore is one.

[mbleigh]

That would be a huge change across many platforms and I don't think it likely to be something we're looking to tackle. In general "Firebase Realtime Database" is often shortened to "Firebase Database" and "Firestore" is always just called "Firestore" (or sometimes "Cloud Firestore" but we're trying to use that less going forward I believe).

Also, they're both databases but Firestore is also realtime 😄

[akauppi]

@mbleigh Thanks for the comment. Seeing you point out Firestore as realtime raises my eyebrows ;) a bit. I haven’t come to the realtime needs of my web app, yet, but thought I would need to do it with RTDB (in addition to Firestore in the same project, which cannot be done), or some Websockets like mechanism.

My use case there is to share temporary information across a group of users; think collaborative editing. The data does not need to be persisted, just distributed.

This is off topic, so muting myself.