Untitled Presentation – How to Name Things



Untitled Presentation – How to Name Things

0 0


naming-things

Guide about naming variables, functions and concepts

On Github hoontw / naming-things

Untitled Presentation

How to Name Things

Two Hard Problems in Computer Science

Cache invalidation Naming things Off-by-one errors

Phil Karlton

Oh hey, these are some notes. They'll be hidden in your presentation, but you can see them if you open the speaker notes window (hit 's' on your keyboard).

IT World

Coding Horrors

if (data) {
	if (data.data) {
		data = data.data;
	}
}

addBottomWhiteBorderIfFirstOfMultipleCarousel();
					

Programming is communication

Lesser mortals write for computers

Great developers write for humans

Experiment

Give a name for the variable

decimal ??? = 0;

forEach (item in cart)
{
	??? += item.Price;
}
					

Conversation

Leverage mutual knowledge

Engage in reflexive thinking

Good names are

Readable Accurate Descriptive Short, but no shorter Unique Memorable

Bad names are

nsReqProd getName() with side-effects Object flushAllTemporaryBuffersIfClearFlagIsSet() VideoItemCover a

Things

Concept

Library | Namespace

Class | Module

Function | Method | Procedure | Routine

Variable

Casing Conventions

PascalCase

camelCase (lower)

snake_case

SCREAMING_SNAKE_CASE

train-case

Naming Conventions

  • C# Pascal for classes, methods; Camel for variables
  • Java Pascal for classes; Camel for methods, variables
  • Python Pascal for classes; Camel/Snake for functions, variables
  • Ruby Camel for classes; Snake for functions, variables
  • JavaScript Camel for constructors; Camel for functions, variables

Stick to the convention of a language, even in mixed-language programming Exception: if developers cross languages frequently

Variable Naming

Ideas

  • Prefer why > what THREE = 3 (bad)
  • Look to domain terminology
  • Identify points of variation
  • Use opposites previous/next
  • Use literal phrases totalCustomersInCanada
  • Contextualize with qualifiers itemPrice vs item.price

Variable Naming

Guidelines

  • Use ASCII characters only
  • Avoid confusing characters oO0iIl1
  • Avoid words with multiple meanings number
  • Avoid overloading established words stack
  • Use full words and standard abbreviations

Variable Naming

Guidelines

  • Standardize order of qualifiers fruitTotal vs totalFruit
  • Spellcheck US or UK
  • Prefix booleans with is- or has-
  • Avoid negatives isInactiveDisabled
  • Pluralize enums and collections

Variable Naming

Exercise

Replace condition with variable

string displayName;

if (patient != null
    && patient.name != null
    && patient.name != ""
    && !privacyPolicy.isAnonymous(patient))
{
	displayName = String.format("Patient {0}", patient.name);
}
else
{
	displayName = "X";
}
					

Function Naming

Ideas

  • Prefer why > how
  • Look to domain terminology
  • Refer to recognized patterns Factory.create()
  • Look for established concepts push, pop, flush
  • Think symmetry open(file)/close(file)

Function Naming

Guidelines

  • Use prepositions for transformations celsiusToFarenheit()
  • Standardize syntax of getters/setters Product.Price() vs Product.GetPrice()
  • Avoid words with multiple meanings number
  • Avoid overloading established words stack
  • Use full words and standard abbreviations

Function Naming

Exercise

Name the function

public TaxRules ??? (PricingContext context)
if (context.hasTaxOverride) {
	return context.getTaxOverride();
}
else if (context.isTaxFree) {
	return new NullTaxRules();
}
else if (context.geo !== null) {
	if (!context.geo.isInEu) {
		return new EuTaxRules();
	}
	else {
		return new DefaultTaxRules();
	}
}
else {
	return null;
}
					

Concept Naming

Ideas

  • Create portmanteaus facetime
  • Use metaphors and analogies token
  • Invoke imagery toast
  • Tell a story bug
  • Consult a thesaurus

Concept Naming

Guidelines

  • Avoid made-up words cystilizer
  • Avoid overloaded words kernel
  • Avoid trademarks Xerox, Google

Concept Naming

Exercise

Pull to refresh components

Fast Company

Fluffy Words Greylist

  • Verbs do, handle, process, perform
  • Nouns callback, car1 car2, data, feature, handler, manager, object, thing
  • Adjectives fast, normal, smart, temp

THE END

Credits

Background Images (in order of appearance)

  • Daniel Lombraña González, "La piedra Rosetta", https://www.flickr.com/photos/teleyinex/4983505622, CC Attribution-ShareAlike 2.0, with modifications to darken image;
  • Board of European Students of Technology, "Discussion group during GA", https://www.flickr.com/photos/bestorg/8733059592/, CC Attribution-NonCommercial 2.0, with modifications to darken image;
  • Pixabay, https://pixabay.com/en/word-cloud-words-tag-cloud-679936/, CC0 Public Domain, with darkened and lightened variants;

This work is licensed under a Creative Commons Attribution 4.0 International License.

Suggestions or errata? Contact TW Hoon at GitHub (username: hoontw).