Naming things real good

Naming stuff: Object Oriented Basics

Jun 1st 2016over 2 years ago

Sep 24th 201822 days ago

Naming stuff: Object Oriented Basics

credit: rawpixel-652639-unsplash.jpg

Let’s look at Object/class design by example…

The Situation

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
  - name
  - email
  - password

* Agent
  - id
  - primaryPhoto
  - name
  - email
  - agentEmail
  - agentPhoneMain
  - agentEmailPrimary
  - agentPhonePrimary
  - agentAddressFull
  - agentCompanyName
  - agentCompanyAddress
  - *userEmail* - 'Pointer' to User table ^^^

Where’s the bug?

Well, technically there’s no bug, simply data in need of re-organization.

Does the following sound familiar?

  1. Any change to your app will necessitate hours of arduous debugging.
  2. Any changing requirements will result in:

schema refactor

Why is naming a field agentEmailPrimary so bad?

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

  1. ‘Locked’ into highly specific name, means agentEmailPrimary probably make your views and related code 0% reusable, and featuring annoyingly recurring bugs like:
  2. 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’ …)
  3. Validation rules/logic are likely duplicated & inconsitent.
  4. Increasingly, your project will resemble a shaky Jenga tower.
  5. Fragility piles up with every single new file, as an extremely high attention to detail is required for even trivial changes
  6. agentEmailPrimary could mean a few different things. Avoid ambiguity with shorter names.
  7. Watch out for silly excess wording. Primary? Just leads to more questions: Is there a Secondary? Is it for their Primary Next-of-kin?

Enough words Dan, what should it look like instead?

A Solution

// Consolidated Schema:

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

I removed the Agent table, as it didn’t contain fields which were unique 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.

Recommended reading includes:

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