Naming things real good

Updated

Reading time ~5 minutes

Let’s tackle something deceptively simple & subtle: Naming

I want to avoid the super-fancy-tech-lingo for this article; and hopefully I can illustrate the issue in a more useful fashion.

While covered in exhausting detail before, the subject matter often gets too technical for the novice programmer to draw any practical understanding. You probably don’t need to read this if the following makes sense Boyce Codd Normal Forms

The Problem - by Example

Have you ever designed a data model (in code, Sql, or excel worksheets)? Does the following look familiar?

*** anti-pattern - don't copy-paste ***
* User
  - id
  - avatarUrl
  - email
  - passwordHash

* Agent
  - id
  - primaryPhoto
  - agentName
  - agentEmail
  - agentPhoneMain
  - agentEmailPrimary
  - agentPhonePrimary
  - agentAddressLine1
  - agentCompanyName
  - agentCompanyAddress
  - *userEmail* - 'Pointer' to User table ^^^

If this is familiar to you, I’ll bet you:

  1. Feel any change to your app will necessitate hours of arduous debugging.
  2. Fear ANY Changing Requirements

schema refactor

The Cost of Bad (Naming) Habits

Why is naming a field agentEmailPrimary the worst?

For starters, you are not creating an entirely new object unto the universe. Over-specificity has some traps:

  1. Strong hint some bad object design/seperation is afoot.
  2. ‘Locked’ into highly specific name, means agentEmailPrimary probably make your views and related code 0% reusable, and featuring annoyingly recurring bugs like:
    • Data not syncing between tables (not obvious if user.email needs to propagate to agent.agentEmail or vice-versa - nevermind complexity of manually implementing where & how to enforce this ‘logic’ …)
    • Validation rules/logic are likely duplicated & inconsitent.
    • Increasingly, your project will resemble a shaky Jenga tower.
    • Fragility piles up with every single new file, as an extremely high attention to detail is required for even trivial changes
  3. agentEmailPrimary could mean a few different things. Avoid ambiguity with shorter names.
    • Watch out for silly excess wording. Primary? Just leads to more questions: Is there a Secondary? Is it for their Primary Next-of-kin?

Hang in there, we’re almost to the solution…

A Solution

// Dan's Recommended Schema Consolidation:

User
  - id
  - role: ['agent', 'lead', 'admin']
  - name
  - phone
  - address
  - email
  - passwordHash
  - company
    - name
    - address

I removed the Agent table, as it didn’t contain fields which were uniquely related to Agents.

All changes were made with these general ideas in mind:

  1. Eliminate unessesary tables. If you have a few dozen tables, this step is mandatory.
  2. Try merge related tables. Important if you are coming from a SQL background to No-SQL
  3. Delete redundant data collection (e.g. remove ActivityLogs table if replaced by Google Analytics)
  4. Try keeping all field names to a single word/noun/pro-noun.
  5. There is no such thing as Agent.agentEmail or Agent.agentPhonePrimary. Period.
  6. By using Highly Specific Names, you cast-in-stone a specific level of code-reusability and durability, well, specifically ZERO %.
  7. Don’t think you are doing yourself any favors with crap like this User.profileSummaryEmail (where ‘profile’ could include contact details for a personal ads site) . This is probably a good point to create a new table, say Profiles which includes Profiles.email.

And if you think I’ve just got crazy ideas, hopefully this will help:

fuck this

Recommended reading includes:

  1. Book: Code Complete
  2. http://phlonx.com/resources/nf3/
  3. https://en.wikipedia.org/wiki/Database_normalization

HOWTO: Stop creating junk Promises using Composable Javascript

## HOWTO: Stop making junk promises> Please take a look at (& star plz) this article's companion Github project, [Escape From Callback Mo...… Continue reading