HOW TO NAME THINGS

Aaron Wang

• It's one of the most important things if you want your code to be readable by others
• Often times, the inability to come up with a name may be a hint to something wrong with your design. Does your method have too many responsibilities? Does your class encapsulate a coherent idea?

Good Names Are

• descriptive
• clear
• consistent

Bad Names Are

• casual
• obscure
• contradictory 

Take it seriously

Don't be rash

Guidelines

• Be consistent, discuss or follow, especially for business domain concepts, don't reinvent by yourself
  • ​When in doubt, double-check
• Follow language specific general conventions, when use a new language, always learn its style guide first
• Be specific as much as possible
  • bad: processData(), what data? what kind of process?
  • good: formatAlertMessages()

• Be descriptive as much as possible, a long name isn't really an issue for modern programming languages, and code is read much more often than it's written
  • CreatePushNotificationChannelForApplicationAsync
• ​Be concise as much as possible, this goes hand by hand with the previous one
  • ​bad: Message.getMessageList()
  • good: Message.getList(), obviously it's list of message
• Look at the context, is it obvious or too verbose in this context?
  • member.number
  • member.memberCardNumber
  • member.cardNumber

• Avoid abbreviations, if you have to, document it, and stick to it
  • CreatePushNotiChanForAppAsync
• ​Avoid confusion, make meaningful difference
  • bad: employeeInfo, employeeData
  • good: employeeContact, employeePayment
• Avoid magic number
  • const scheduleDate =  date.subtract(5, 'hour')
• For booleans
  • positive is better than negative
  • isEnabled, shouldAutoUpdate, canAddUser

• Use plural and singular properly
  • bad: for dev in device, for device in deviceList
  • good: for device in devices
• Use tense properly
  • bad: pushMessagesCount
  • good: pushedMessagesCount
• Spell it right, look up in the dictionary if you're not sure
  • data is the plural form of datum, don't use datas
• Use verb + noun form for functions/methods
• Use [adj + ]noun form for classes

Common Bad Names

• str1
• tmpData
• for personItem in personArr 
• isEnable
• imgW
• mods
• sendAt
• doLaunch()
• registUnique()
• lunch()
• formateMsg()
• enQueue()
• dbOpen()

Golden Rules

• Consistency, Consistency, Consistency
• Spend time to think
  • ​Otherwise you're probably picking bad names
• Don't be afraid to rename
  • I often find my first choice is inappropriate

Improve Tips

• Read open source code
  • There are a bunch of names conventionally used by world wide developers, you better to know them and use them
• Keep practice your English skills
  • ​Vocabulary
  • Syntax, good code reads like an article
    • ​