Renaming matches and _matchesInfo

[dichotommy]

Renaming matches and matchesInfo

Intro

I care a lot about parameter/variable/function names. Partly it's because I'm a perfectionistic writer who loves word puzzles. Finding the perfect combination of words to say as much as possible in as few characters as possible is a tantalizing challenge. Guilty as charged 😈

Mostly, though, it's because I have been a learner of complex software in the past and have been slowed down by poor naming. I believe that descriptive names can save all developers a lot of time because they help us understand at a glance whether we want to learn more about something.

matches and matchesInfo

In that regard, I have always thought that matches is not an effective parameter name.

I go by the following test: can you guess what this parameter does based on the name?

With a name like matches, I can understand that it relates to search hits somehow, but not much beyond that. It's really vague.

Similar for _matchesInfo, the object added to the response in hits when you make a search using matches: it's clear that it's related to matches, but that's basically all.

If we don't plan on adding additional functionality to this parameter in the foreseeable future, I think it would be a good idea to give it and the returned object more descriptive names. The goal would be that a reader scrolling down a long list of search parameters could understand basically what this parameter does before committing to reading a lengthy explanation.

A name with an active verb would also make more intuitive sense with the boolean data type, e.g. locateMatches: true.

Some proposals

Proposal A

matches -> returnMatchesPosition
_matchesInfo -> matchesPosition

Pros

• descriptive name: it's fairly clear what the parameter will do, and what will happen if you set it to true
• obvious relationship between parameter name and returned field name

Cons

• parameter name is long: 21 chars, the same as our longest search parameter attributesToHighlight. Of course, "return" could be changed to "get" to save characters
• matches can be a verb or a noun in English, so this name can be read multiple ways. Can lead to it sounding like "word soup" to some readers

Proposal B

matches -> locateMatches
_matchesInfo -> matchesLocation

Pros

• much shorter name than previous proposal at 13 chars
• clearer name with less ambiguity

Cons

• the parameter name and the returned field name are extremely similar and could be confused

Proposal C

matches -> position
_matchesInfo -> positionInfo

Pros

• shortest name, almost as short as matches

Cons

• name is not as descriptive as other options (such as A)
• position already means something in Meilisearch (but it's pretty esoteric)
• very minor change, and may not be a concrete improvement

Conclusion

I'm not particularly satisfied with any of these proposals (big surprise, the perfectionist isn't satisfied 🙃), but I am curious if anyone shares my feelings about matches, or if any of my suggestions seem to be heading in the right direction. Thanks for reading and please let me know what you think ☺️

[gmourier]

Thanks, @dichotommy!

To give you some context, I think this field can potentially be deprecated and deleted in the future for a v1.0. Users seem to be using it because of the lack of custom highlighting and cropping behavior that Meilisearch has. We worked on solving a good part of it on v0.27.

I really like proposal A. What do you think of showMatchesPosition instead of returnMatchesPosition ?

[bidoubiwa]

Position is indeed the most appropriate name in this context, I don't really like return but I'm not sure show is the right word for this context.

• displayMatchesPosition
• addMatchesPosition

Maybe something like this?

[gmourier]

Why not! return may be too technical.

To add consistency, we need to choose a term that makes it clear that the response will include metadata so the chosen term among show, display, add, ... should also be considered for other fields like facetDistribution for example.

[bidoubiwa]

should also be considered for other fields like facetDistribution for example.

This is a great idea! It is confusing that both fields are named the same but are different depending on the environment.

[curquiza]

I like show, but it might be really personal 😇

[bidoubiwa]

I don't know if show is the most suited word. @dichotommy @guimachiavelli what do you think?

[bidoubiwa]

matchesPosition is the perfect field name in the response object for me!

[curquiza]

I like your suggestion!
To be sure we agree, you mean _matchesPosition for the consistency with _formatted?

[bidoubiwa]

Absolutely

[bidoubiwa]

Another possibility just for the brainstorm is indexOfMatches because of this IndexOf method in javascript. I'm not sure it is very intuitive but just in case it is a possibility

[gmourier]

I find this one a bit convoluted, it doesn't really give a clue about what the user will get at the end in my opinion

[curquiza]

Hello, thanks for your different feedback!
After discussion with @gmourier here are the final suggestion (not the definitive decision)

For the request body

Current name: matches

For the renaming, we think adding a verb like show, display, add...

Knowing this, here are the potential candidate

• displayMatchesPosition
• showMatchesPosition
• addMatchesPosition

For the response body

Current name: _matchesInfo

_matchesPosition seems to be a good candidate. So I don't put any other suggestion except if someone strongly disagrees with it.

---

Before sending any survey, WDYT about this short list?

[curquiza]

Final survey - in the search REQUEST, replace matches?

Please take a look at the previous discussion before voting, ensuring you have the whole context 😇

Currently in the search REQUEST, to get the position of each term matching the query words in the returned documents, the users have to set the matches parameter to true (default: false).

Here are the new alternatives:
😄 matches (keep the current one)
🎉 displayMatchesPosition
❤️ showMatchesPosition
🚀 addMatchesPosition

[curquiza]

Final survey - in the search RESPONSE, replace _matchesInfo?

Please take a look at the previous discussion before voting, ensuring you have the whole context 😇

Currently in the search RESPONSE, Meilisearch returns the information regarding the matches position in the _matchesInfo field.

Here are the alternatives:
😄 _matchesInfo (keep the current one)
🎉 _matchesPosition
❤️ _matchesPositionInfo
🚀 _positionInfo

[curquiza]

Hello, here are the final namings:
In the request body: showMatchesPosition
In the response body: _matchesPosition

@gmourier I let you update this spec: meilisearch/specifications#135 😇

[gmourier]

Specified in meilisearch/specifications#135.

Locking the discussion.