giving code a good name

Giving Code a

Good Name

@KevlinHenney

It's just naming.

It's just semantics.

It's just meaning.

/ WordFriday

code, noun

▪ a set of instructions for a computer

▪ a computer program, or a portion thereof

▪ a system of words, figures or symbols used to represent others,

especially for the purposes of secrecy

▪ a set of conventions or principles governing behaviour or activity in

a particular domain

Concise Oxford English Dictionary ∙ Oxford English Dictionary ∙ Merriam-Webster's Collegiate Dictionary

As a

I want

So that

$Role

$Feature

$Benefit

As a

I want

So that

programmer

$Feature

$Benefit

As a

I want

So that

programmer

good identifier names

$Benefit

As a

I want

So that

programmer

good identifier names

I can read code

As a

I want

So that

programmer

good identifier names

I can read and understand code

As a

I want

So that

programmer

good identifier names

I can spend less time determining the meaning of code and more time coding meaningfully

As a

I want

So that

programmer

???

I can spend less time determining the meaning of code and more time coding meaningfully

Signal-to-noise ratio (often abbreviated SNR or S/N) is a

measure used in science and engineering that compares the

level of a desired signal to the level of background noise.

Signal-to-noise ratio is sometimes used informally to refer

to the ratio of useful information to false or irrelevant data

in a conversation or exchange.

http://en.wikipedia.org/wiki/Signal_to_noise_ratio

To be, or not to be: that is the question:

Whether 'tis nobler in the mind to suffer

The slings and arrows of outrageous fortune,

Or to take arms against a sea of troubles,

And by opposing end them?

William Shakespeare

Hamlet

Continuing existence or cessation of existence:

those are the scenarios. Is it more empowering

mentally to work towards an accommodation of the

downsizings and negative outcomes of adversarial

circumstance, or would it be a greater enhancement

of the bottom line to move forwards to a challenge

to our current difficulties, and, by making a

commitment to opposition, to effect their demise?

Tom Burton

Long Words Bother Me

People will be using the words you

choose in their conversation for the

next 20 years. You want to be sure

you do it right.

Unfortunately, many people get all

formal [...]. Just calling it what it is

isn't enough.

public class ConfigurationManager{

...}

public class Configuration{

...}

They have to tack on a flowery,

computer science-y, impressive

sounding, but ultimately

meaningless word, like Object,

Thing, Component, Part, Manager,

Entity, or Item.

Comments

A delicate matter, requiring taste and judgement. I tend to err on the side of eliminating comments, for several reasons. First, if the code is clear, and uses good type names and variable names, it should explain itself. Second, comments aren't checked by the compiler, so there is no guarantee they're right, especially after the code is modified. A misleading comment can be very confusing. Third, the issue of typography: comments clutter code.

Rob Pike, "Notes on Programming in C"

There is a famously bad comment style:

i=i+1; /* Add one to i */

and there are worse ways to do it:

/**********************************

* *

* Add one to i *

* *

**********************************/

i=i+1;

Don't laugh now, wait until you see it in real life.

Rob Pike, "Notes on Programming in C"

A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments.

Kevlin Henneyhttps://twitter.com/KevlinHenney/status/381021802941906944

http://eightyeightgames.com/2011/03/14/rollrover-source-analysis/

if (portfolioIdsByTraderId.get(trader.getId()).containsKey(portfolio.getId()))

{...

}

Dan North"Code in the Language of the Domain"

if (trader.canView(portfolio)){

...}

Dan North"Code in the Language of the Domain"

Agglutination is a process in linguistic morphology

derivation in which complex words are formed by

stringing together morphemes, each with a single

grammatical or semantic meaning.

Languages that use agglutination widely are called

agglutinative languages.

http://en.wikipedia.org/wiki/Agglutination

pneumonoultramicroscopicsilicovolcanoconiosis

Rindfleischetikettierungsüberwachungsaufgabenübertragungsgesetz

fylkestrafikksikkerhetsutvalgssekretariatslederfunksjonene

muvaffakiyetsizleştiricileştiriveremeyebileceklerimizdenmişsinizcesine

hippopotomonstrosesquipedaliophobia

http://www.bonkersworld.net/object-world/

http://www.bonkersworld.net/object-world/

OBJECT-ORIENTED

VenetianBlind Door

Television

PictureGlass

SofaTelevisionRemoteControl

Peephole

AccessViolationException

ArgumentOutOfRangeException

ArrayTypeMismatchException

BadImageFormatException

CannotUnloadAppDomainException

EntryPointNotFoundException

IndexOutOfRangeException

InvalidOperationException

OverflowException

AccessViolation

ArgumentOutOfRange

ArrayTypeMismatch

BadImageFormat

CannotUnloadAppDomain

EntryPointNotFound

IndexOutOfRange

InvalidOperation

Overflow

ArgumentException

ArithmeticException

ContextMarshalException

FieldAccessException

FormatException

NullReferenceException

ObjectDisposedException

RankException

TypeAccessException

Argument

Arithmetic

ContextMarshal

FieldAccess

Format

NullReference

ObjectDisposed

Rank

TypeAccess

InvalidArgument

InvalidArithmeticOperation

FailedContextMarshal

InvalidFieldAccess

InvalidFormat

NullDereferenced

OperationOnDisposedObject

ArrayRankMismatch

InvalidTypeAccess

Omit needless words.

William Strunk and E B White

The Elements of Style

Naomi EpelThe Observation Deck

LoanMember BookCopy

LoanIMember IBookCopy

Member BookCopy

Loan

Member BookCopy

role, noun

▪ an actor's part in a play, film, etc.

▪ a person or thing's function in a particular

situation

▪ a function, part or expected behaviour

performed in a particular operation or process

Concise Oxford English Dictionary ∙ Merriam-Webster's Collegiate Dictionary

LoanBorrower LoanItem

Member BookCopy

interface

TreeBuilderParser

TreeBuilderParser

BuilderImpl

TreeParserListenerParser

Builder

Tree

ParserListenerParser

Builder

ConnectionConnection

Factory

ConnectionImpl

ConnectionConnection

Pool

PooledConnection

Everybody knows that TDD stands for Test Driven Development. However, people too often concentrate on the words "Test" and "Development" and don't consider what the word "Driven" really implies.

For tests to drive development they must do more than just test that code performs its required functionality: they must clearly express that required functionality to the reader.

That is, they must be clear specifications of the required functionality. Tests that are not written with their role as specifications in mind can be very confusing to read.

Nat Pryce and Steve Freeman"Are Your Tests Really Driving Your Development?"

public class Stack<T>{

private public Stack() public int Depth public T Top public void Push(T newTop) public void Pop()

}

[TestFixture]public class StackTests{

[Test]public void TestConstructor() [Test]public void TestDepth() [Test]public void TestTop() [Test]public void TestPush() [Test]public void TestPop()

}

[TestFixture]public class StackTests{

[Test]public void Constructor() [Test]public void Depth() [Test]public void Top() [Test]public void Push() [Test]public void Pop()

}

public class Stack<T>{

private public Stack() public int Depth public T Top public void Push(T newTop) public void Pop()

}

public class Stack<T>{

private

public int Depth public T Top public void Push(T newTop) public void Pop()

}

[TestFixture]public class StackTests{

[Test]public void Depth() [Test]public void Top() [Test]public void Push() [Test]public void Pop()

}

methodtest

test

test

method

method

test

test

namespace Stack_spec{

[TestFixture]public class A_new_stack{

[Test]public void has_no_depth()

}[TestFixture]public class An_empty_stack{

[Test]public void throws_when_queried_for_its_top_item() [Test]public void throws_when_popped() [Test]public void acquires_depth_by_retaining_a_pushed_item_as_its_top()

}[TestFixture]public class A_non_empty_stack{

[Test]public void becomes_deeper_by_retaining_a_pushed_item_as_its_top() [Test]public void on_popping_reveals_tops_in_reverse_order_of_pushing()

}}

namespace Stack_spec{

[TestFixture]public class A_new_stack{

[Test]public void has_no_depth()

}[TestFixture]public class An_empty_stack{

[Test]public void throws_when_queried_for_its_top_item() [Test]public void throws_when_popped() [Test]public void acquires_depth_by_retaining_a_pushed_item_as_its_top()

}[TestFixture]public class A_non_empty_stack{

[Test]public void becomes_deeper_by_retaining_a_pushed_item_as_its_top() [Test]public void on_popping_reveals_tops_in_reverse_order_of_pushing()

}}

As a

I want

So that

programmer

???

I can spend less time determining the meaning of code and more time coding meaningfully

As a

I want

So that

programmer

identifiers to communicate directly and with intent

I can spend less time determining the meaning of code and more time coding meaningfully

At some level

the style

becomes the

substance.