Naming Maps in ES6
Help your vars explain themselves to someone down the road
For a year and a half I worked writing APEX, Salesforce’s cloud based programming language. It’s an interesting beast full of rules about how much time a sequence of code can run, when you can and cannot make external calls and even how often you can save. These sort of limitations lead to small for loops generating and using targeted Sets and Maps.
When I left APEX and took up Node.js for Social Tables I found that while JSObjects are sort of like Maps, the limitation of string keys meant that keying was rather basic. But with ES6 on us and and the prospect of keying Maps with anything (even Maps!) I figured it was time to start rethinking how to best name Maps so that my vars explain themselves.
Note
I won’t be talking about why you might want to use Maps or how to best to use them. If that is something you want/need to learn more about, here is an article to check out.
Basic Maps
Here we have a result of user objects coming from a db table called users. For some reason we need to create a map of these users so that we can get all the users by their team ids.
As I see it there are a few ways people might name this Map var:
- teamUsers
- usersByTeamId
- teams
- users
- usersByTeam
Now, lets throw out 3 and 4 because neither of these show the relationship which the Map describes. While I’m sure people will use teams from time to time (much like people use result in callbacks) you shouldn’t. It will cause variable scope conflict.
teamUsers is an good enough name. It tells us that what we’re dealing with is users grouped by their team but that might lead one to try and get the users from the map by requesting it via a team object. It also doesn’t speak Map to me. Maps are values by keys and this name, while maybe a bit awkward for an 2D array, might very well be used for a 2D array.
Lastly we have usersByTeam and usersByTeamId. I like both of these names because the key value relationship is explicit. We have a group (array) of users as a value keyed by either a Team or a Team Id.
Now, currently we don’t have a list of team objects so what we will have to index with is a value from the users table which is the team_id, so I’d go with usersByTeamId.
I guess another option might have been userByTeamId. This seems rather silly so lets just say if you’re value is an array, make your value entity name plural.
Nested Maps
Now in this second example we’re dealing with nested Maps. Somehow and for some reason we need to group a user’s commits and a user’s team by the user itself. To do this we find ourself querying the users table again, looping through the users result array and pulling out the commits and team from other maps we’ve already indexed.
To make this nested Map we need to first decide what we’re going to name the child map. This proves a bit weird using the convention I mentioned in the first example as we’ll be keying these values with a word (ie: team and commits). For these kind of Maps (which are as close to JSObjects as you can get!) I like just binding the attributes with an And. commitsAndTeam. Here you’ll note that commits is plural because commitsAndTeam.get(“commits”) will return an array and team is singular because commitsAndTeam.get(“team”) will return a single entity.
Now that we’ve named the child map we need to name its parent. Here we will be indexing the map with user objects. So the key will be a user and the value will be commitsAndTeam. The map name? commitsAndTeamByUser.
Limitations
Obviously this sort of naming convention can get very long. What if, for instance, we wanted to index commits, team, branches, pull requests, issues by user? Would we really name our var commitsAndTeamAndBranchesAndPullRequestsAndIssuesByUser? I hope not. But, if you did, I’d most definitely know what I was getting into when I came to refactor your code a year later.
