Clean up variable names

[mpenkov]

I think go with (a) now and open up a ticket to clean up names globally later. This PR is already large enough.

Originally posted by @mpenkov in https://github.com/_render_node/MDExOlB1bGxSZXF1ZXN0MzQ5Mjk1NTk1/timeline/more_items

[piskvorky]

The link in the description doesn't work, but I believe this is related to the discussion in #2698 around *2vec attributes: .w2v vs .word_vectors, .docvecs vs .tag_vectors, etc.

[mpenkov]

Yeah, looks like the github UI messed up the link. Your reference is correct.

[piskvorky]

@mpenkov @gojomo what's the conclusion? I'll have some time this week (I'm on holidays) so I'd like to finish as much as I can, to unblock 4.0.0.

Should I rename the variables?

Pros:

• clearer, more explicit naming
• if we do it, 4.0.0 is the place to do it

Cons:

• breaks existing code
• lots of tedious replacements in code, docs, tutorials
• possible divergence from other implementations (facebook, google)… although that may be a plus too.

[mpenkov]

We can do this at any time, so if your priority is to unblock 4.0.0, then it's probably more productive and rewarding to do something else.

This sort of renaming can happen at any time in the future, right?

[piskvorky]

• breaks existing code
• if we do it, 4.0.0 is the place to do it

One of the things most suitable for a major release bump.

[gojomo]

Agree that it's better to do core naming cleanup in fewer releases and correlated with 'major' increments – such that when people notice old code doesn't work (or generates new warnings), they check some release-notes, notice all the changes required, make them in one batch-of-effort, then are OK for as-long-as-possible through future releases.

My proposal remains to leave the attributes on the *2Vec models as .wv for the subcomponent word-vectors object on all classes, and .dv for the parallel subcomponent doc-vectors object on a Doc2Vec model. Yes, it's a small deviation from the usual Pythonic 'be explicit & avoid abbreviations'. But the abbreviations are pretty clear & compact & save a lot of typing/horizontal space in very-frequent problem-domain operations.

That is, these are central enough to warrant bootstrapping a convention/library-specific lingo. I don't see it as too different than having embraced 'doc' instead of 'document', and 'vec' instead of 'vector', and 'hs' instead of 'hierarchical_softmax', and so forth. And, I don't look forward to all the lines of library or demo/tutorial code that would start to need wrapping if all .wv uses change to .word_vectors.

But, renaming them .word_vectors and .doc_vectors (or perhaps to be pedantically-consistent with other internal naming, .tag_vectors instead of .doc_vectors) would also be defensible, if someone wants to do the big search-and-replace.

[piskvorky]

Let me close this. Why? I'm thinking:

1. I doubt we'll get to it in time for 4.0.0 (and doing it later would be bad);
2. (at least) @gojomo is not in favour;
3. it's a lot of work that breaks existing code for aesthetic reasons = not critical.