SlideShare une entreprise Scribd logo
1  sur  91
@PeterHilton
http://hilton.org.uk/
the hardest problem in programming
How to name things:
15 years as 

the dev team’s
only native
English speaker…
@PeterHilton • 2
How to name things: the hardest problem in programming
George Orwell’s
rules for naming
How to name things, by G. Orwell
‘What is above all needed is to 

let the meaning choose the word, 

and not the other way around.
… the worst thing one can do with
words is surrender to them.
‘When you think of a concrete
object, you think wordlessly,
and then, if you want to
describe the thing you have
been visualising you probably
hunt about until you find the
exact words that seem to fit it.
‘When you think of something
abstract you are more inclined to
use words from the start, and
unless you make a conscious effort
to prevent it, the existing dialect
will come rushing in and do the job
for you, at the expense of blurring
or even changing your meaning…
1. Never use a metaphor, simile, or other figure of
speech which you are used to seeing in print.
2. Never use a long word where a short one will do.
3. If it is possible to cut a word out, always cut it
out.
4. Never use the passive where you can use the
active.
5. Never use a foreign phrase, a scientific word, or
a jargon word if you can think of an everyday
English equivalent.
6. Break any of these rules sooner than say
anything outright barbarous.
‘These rules sound elementary,
and so they are, but they demand
a deep change of attitude in
anyone who has grown used to
writing in the style now
fashionable.’
Politics and the English Language

(1946)
1. ‘Never use a metaphor, simile, or
other figure of speech which you are
used to seeing in print’
(beware of over-using design patterns, and
using their names just because you’re used
to seeing them in code)
e.g.
AbstractConfigurationFactory
11@PeterHilton •
2. ‘Never use a long word 

where a short one will do’
(prefer concise variable names, 

use longer names for a good reason)
e.g.
company_person_collection  
vs
staff
12@PeterHilton •
3. ‘If it is possible to cut a word out,
always cut it out’
(avoid additional words that don’t add any
meaning to a name)
e.g.
AbstractObjectFormatterProxy  
…
13@PeterHilton •
AbstractAnnotationConfigDispatcher
ServletInitializer  
14@PeterHilton •
org.springframework.web.servlet.support.
‘This is like homeopathy. 

What you’ve done is
you’ve diluted the meaning
until it’s all gone.’
@KevlinHenney
4. ‘Never use the passive 

where you can use the active’
(respect grammatical rules for identifiers)
e.g.
class  PlanEvents  
vs
class  EventPlanner  
or even
class  Scheduler  
15@PeterHilton •
5. ‘Never use a foreign phrase, a
scientific word, or a jargon word if
you can think of an everyday English
equivalent’
(don’t let technical jargon from a library
pollute your domain model)
(beware libraries that import ‘foreign’
naming from one language to another)
e.g. ShipmentMonad
16@PeterHilton •
6. ‘Break any of these rules sooner
than say anything outright barbarous’
(don’t blame me if your code is featured on
The Daily WTF)
Note: a lot depends on context;
publishing library code is not the same as
maintaining private application code
17@PeterHilton •
It sounds like
writing prose 

is as hard as 

writing code.
Who knew? @PeterHilton • 18
Advice from 

other writers
How to name things: the hardest problem in programming
21
‘Write with the 

door closed, 

rewrite with the 

door open.’
Stephen King on pair programming
@PeterHilton •
warriorwoman531 / CC BY-ND 2.0
23
Anne Rice on development hardware
‘I find the bigger 

the monitor, 

the better the
concentration.’
@PeterHilton •
How to name things: the hardest problem in programming
Ernest Hemingway on user personas
‘When writing a novel a
writer should create living
people; 

people not characters. 

A character is a caricature.’
25@PeterHilton •
How to name things: the hardest problem in programming
W. Somerset Maugham on 

enterprise architecture
‘There are three rules for
writing the novel.
Unfortunately, no one
knows what they are.’
27@PeterHilton •
ranh / CC BY 2.0
Neil Gaiman on productivity
‘Write.



‘Put one word after another. 

Find the right word, put it down.


‘Finish what you’re writing. Whatever you
have to do to finish it, finish it.’
29@PeterHilton •
Neil Gaiman on code review
‘Put it aside.
Read it pretending you’ve never read it
before.
Show it to friends whose opinion you
respect’
30@PeterHilton •
Neil Gaiman on review feedback
‘When people tell you something’s
wrong or doesn’t work for them,
they are almost always right.



‘When they tell you exactly what
they think is wrong and how to fix it,
they are almost always wrong.’
31@PeterHilton •
Neil Gaiman on refactoring
‘Fix it.
‘Remember that, sooner or later, before it ever
reaches perfection, you will have to let it go
and move on and start to write the next thing.
‘Perfection is like chasing the horizon. 

Keep moving.’
32@PeterHilton •
Neil Gaiman on humour in code
‘Laugh at your own jokes.’
33@PeterHilton •
Neil Gaiman on open source
‘The main rule of writing is
that if you do it with
enough assurance and
confidence, you’re allowed
to do whatever you like.’
34@PeterHilton •
Summary of advice from writers
Advice from writers is useful, and 

not only about naming.
Writers have been at it for centuries;
programming is merely decades old.
Also, their advice is better written.

And funnier.
35@PeterHilton •
Getting it right
means a struggle
for every single
word.
@PeterHilton • 36
Naming things
badly
Phil Karlton on naming
‘There are only two hard things 

in Computer Science: 

1. cache invalidation and
2. naming things.’
38@PeterHilton •
0. off-by-one errors
Lewis Carroll on bad naming
‘When I use a word,’
Humpty Dumpty said,
in rather a scornful tone,
‘it means just what I choose it to mean -
neither more nor less.’
Through the Looking-Glass, 

and What Alice Found There (1871) 39@PeterHilton •
Deliberately meaningless names
In theory, foo is only used as a placeholder
name (because it doesn’t mean anything)
40@PeterHilton •
Sam Gardiner on naming
‘If you don’t know what a thing should be
called, you cannot know what it is.
If you don’t know what it is, you cannot sit
down and write the code.’
http://97things.oreilly.com/wiki/index.php/
A_rose_by_any_other_name_will_end_up_as_a_cabbage
41@PeterHilton •
What is the worst ever

variable name?
data  
What is the second-worst name?
data2  
What is the third-worst name ever?
data_2
42@PeterHilton •
Abbreviations are ambiguous
Is char a character or characteristic?
Does mod mean modify or modulo?
What about acc, pos or auth?
Sadly, fab was just a function ƒ:A➞B

(not fabulous)
Allow one exception: id for ‘identity’
43@PeterHilton •
One letter is too short
Local variable: what is the meaning?
var  a  =  42;  
The exception that proves the rule?
for  (int  i  =  1;  i  <  42;  ++i)  
Not an improvement: 

ii, jj, kk 44@PeterHilton •
Functional programming:

one letter is still too short
45@PeterHilton •
def  modp[C]

        (f:  B1     (B2,  C),  a:  A1):  

        (A2,  C)  =  {  
    val  (b,  c)  =  f(get(a))  
    (set(a,  b),  c)  
}  
https://github.com/scalaz/scalaz/blob/series/7.2.x/core/src/main/scala/scalaz/Lens.scala
46@PeterHilton •
()
How to name things: the hardest problem in programming
How to name things: the hardest problem in programming
How to name things: the hardest problem in programming
Multiple words can be replaced by
more specific words
What’s an appointment_list?
a calendar  
What’s an company_person?
an employee or perhaps an owner  
What’s a text_correction_by_editor?
just an edit
50@PeterHilton •
Vague words are vague
51@PeterHilton •
Alan Green wrote* about vague words, e.g.
InvoiceManager  
TaskManager  
‘Manager’ is very imprecise; one of its
meanings may be the word you want:
Bucket, Supervisor, Planner, Builder
* http://www.bright-green.com/blog/2003_02_25/naming_java_classes_without_a.html
Vague words are vague
52@PeterHilton •
get at the start of a method name is

appropriate only for returning a field value.
If it does anything else, or gets the data
from anywhere else, use another name:
fetch, find, lookup, create, calculate,
derive, concoct,
Wrong words are wrong,
Synonyms are confusing
order ≠ shipment
carrier ≠ broker
shipment ≠ transport leg
shipment = consignment
carrier = transporter
transport leg = journey
53@PeterHilton •
Apache Camel - http://camel.apache.org
(Java enterprise 

middleware example)
//  Not  enough  jokes  in  code  
/**  Configure  and  start  Apache  Camel.  */  
{  
    Logger.info("Starting  Camel…")  
    val  context  =  new  DefaultCamelContext()  
    configuredRoutes  foreach  {  route  =>  

      context.addRoutes(route)

    }  
    context.start()  
}
def  mountCamel()  {
How to name things: the hardest problem in programming
Property accessors revisited
In a numeric library, these method names
would be irresistible, but inadvisable:
getEven  
getReal  
getAround  
getRoundTo  
getRichQuick  
getJoke 57@PeterHilton •
Summary of naming things badly
Meaningless: foo
Too general: data
Too short: a
Too long: text_correction_by_editor  
Abbreviated: acc  
Vague: InvoiceManager  
Wrong: order  
Just not funny: startCamel 58@PeterHilton •
Better naming
How to solve the naming problem
Become a better writer.
Improve your vocabulary.
Adopt better naming practices.
Work on it.
60@PeterHilton •
Become a better writer
Naming is just one part of writing,
and is mostly about vocabulary.
You may remember working on vocabulary
as part of learning a foreign language.
Not having had to learn a foreign language
is a mixed blessing.
61@PeterHilton •
Improve your general vocabulary
Read books, especially funny novels.
Play word games with someone who
always wins, until they don’t.
62@PeterHilton •
63@PeterHilton •
Piotr / CC BY 2.0
How to name things: the hardest problem in programming
Improve your general vocabulary
Use your dictionary and thesaurus…
65@PeterHilton •
How to name things: the hardest problem in programming
@PeterHilton • 67
A sandwich walks
into a pub.
The barman says,

‘I’m sorry, we
don’t serve food.’
Tell jokes
Many jokes rely on word-play.
It takes practice to think of puns quickly.
Puns are important for naming, because
they rely on double-meanings.
Spotting double-meanings is the essential
skill for avoiding ambiguous names.
68@PeterHilton •
Adopt better naming practices
69@PeterHilton •
Start with meaning and intention.
Use words with precise meanings.
Prefer fewer words in names.
No abbreviations in names, except id.
Use code review to improve names.
Remember: ‘rename’ is the simplest but
most effective refactoring. Use it.
Replace vague words with more
specific synonyms
Manager  
Object  
Data  
Thing  
Info  
Amount  
Details

do  
execute  
perform  
operate  
manage  
handle  
get
70@PeterHilton •
Overcome fear of renaming
The only thing harder than naming is
renaming.
Renaming requires change, a conversation,
and new understanding.
‘Refactor’ is the safest refactoring.
71@PeterHilton •
Chapter 10:
The power of
variable names
Chapter 2:
Meaningful
Names
Chapter 2:
Names
Gather domain-specific vocabulary
Scan the domain model entities’ Wikipedia
pages for names of related concepts.
Read novels set in your customer’s domain,
to learn their jargon.
Find out what they really mean.
75@PeterHilton •
Chapter 2:
Communication
and the use of
language
How to name things: the hardest problem in programming
How to name things: the hardest problem in programming
Programmers Stack Exchange - question by Tragedian answered by gnat / CC-BY-SA
For naming, there are six techniques
that were proven to work for me:
1. spend a lot of time on inventing names
2. use code reviews
3. don’t hesitate to rename
4. spend a lot of time on inventing names
5. use code reviews
6. don’t hesitate to rename
Additional benefits
If you become a better writer,
you could use your new skills
… for writing
80@PeterHilton •
Writing whole
sentences in code
‘Most of the things programmers
say about comments in code are
excuses for not writing any
comments at all.’
@PeterHilton
82@PeterHilton •
Comments: the basics
1. Don’t say what the code does

(because the code already says that)
2. Don’t explain awkward logic

(improve the code to make it clear)
3. Don’t add too many comments

(it’s messy and they’ll get out of date)
83@PeterHilton •
Explain why the code exists
Even perfect code cannot explain its own
existence.
When should I use this code?
When shouldn’t I use it?
What are the alternatives to this code?
84@PeterHilton •
Discover which comments are hard
to write, and why
If a comment is easy to write, then that
code doesn’t need a comment.
Write a one-sentence comment, for 

every class and method, to start with.
85@PeterHilton •
‘A common fallacy is to assume
authors of incomprehensible code
will somehow be able to express
themselves lucidly and clearly in
comments.’
@KevlinHenney
86@PeterHilton •
Acknowledge that writing
(comments) is a specialist skill
On a cross-functional development team,
not everyone is good at visual design.
The same goes for writing about code.
Work out who is a better writer.
Get help with writing comments.
87@PeterHilton •
How to write good comments
(summary)
1. Try to write good code first.
2. Try to write a one-sentence comment.
3. Refactor the code until the comment is
easy to write.
4. Now write a good comment.
5. Don’t forget the rules of good writing
(e.g. remove unnecessary comments).
88@PeterHilton •
Summary
Summary
1. Naming is hard
2. Get inspiration from great writers
3. Read novels, tell jokes, play games
4. Expand your vocabulary
5. Try actual writing; 

start with comments,

try blogging, or even write a book
90@PeterHilton •
@PeterHilton
http://hilton.org.uk/
Peter Hilton is available for company
and conference presentations
peter.hilton@gmail.com

Contenu connexe

Tendances

Introduction to DataFusion An Embeddable Query Engine Written in Rust
Introduction to DataFusion  An Embeddable Query Engine Written in RustIntroduction to DataFusion  An Embeddable Query Engine Written in Rust
Introduction to DataFusion An Embeddable Query Engine Written in RustAndrew Lamb
 
Schema Evolution for Resilient Data microservices
Schema Evolution for Resilient Data microservicesSchema Evolution for Resilient Data microservices
Schema Evolution for Resilient Data microservicesVinícius Carvalho
 
Building Fullstack Serverless GraphQL APIs In The Cloud
Building Fullstack Serverless GraphQL APIs In The CloudBuilding Fullstack Serverless GraphQL APIs In The Cloud
Building Fullstack Serverless GraphQL APIs In The CloudNordic APIs
 
OLTP+OLAP=HTAP
 OLTP+OLAP=HTAP OLTP+OLAP=HTAP
OLTP+OLAP=HTAPEDB
 
Apache NiFi Record Processing
Apache NiFi Record ProcessingApache NiFi Record Processing
Apache NiFi Record ProcessingBryan Bende
 
How to understand and analyze Apache Hive query execution plan for performanc...
How to understand and analyze Apache Hive query execution plan for performanc...How to understand and analyze Apache Hive query execution plan for performanc...
How to understand and analyze Apache Hive query execution plan for performanc...DataWorks Summit/Hadoop Summit
 
Data Storage Tips for Optimal Spark Performance-(Vida Ha, Databricks)
Data Storage Tips for Optimal Spark Performance-(Vida Ha, Databricks)Data Storage Tips for Optimal Spark Performance-(Vida Ha, Databricks)
Data Storage Tips for Optimal Spark Performance-(Vida Ha, Databricks)Spark Summit
 
Espresso: LinkedIn's Distributed Data Serving Platform (Paper)
Espresso: LinkedIn's Distributed Data Serving Platform (Paper)Espresso: LinkedIn's Distributed Data Serving Platform (Paper)
Espresso: LinkedIn's Distributed Data Serving Platform (Paper)Amy W. Tang
 
Adobe Behance Scales to Millions of Users at Lower TCO with Neo4j
Adobe Behance Scales to Millions of Users at Lower TCO with Neo4jAdobe Behance Scales to Millions of Users at Lower TCO with Neo4j
Adobe Behance Scales to Millions of Users at Lower TCO with Neo4jNeo4j
 
Introduction to the Web API
Introduction to the Web APIIntroduction to the Web API
Introduction to the Web APIBrad Genereaux
 
Graphql Intro (Tutorial and Example)
Graphql Intro (Tutorial and Example)Graphql Intro (Tutorial and Example)
Graphql Intro (Tutorial and Example)Rafael Wilber Kerr
 
Apache Druid 101
Apache Druid 101Apache Druid 101
Apache Druid 101Data Con LA
 
Parquet performance tuning: the missing guide
Parquet performance tuning: the missing guideParquet performance tuning: the missing guide
Parquet performance tuning: the missing guideRyan Blue
 
善用 MySQL 及 PostgreSQL - RDBMS 的逆襲 - part1
善用 MySQL 及 PostgreSQL - RDBMS 的逆襲 - part1善用 MySQL 及 PostgreSQL - RDBMS 的逆襲 - part1
善用 MySQL 及 PostgreSQL - RDBMS 的逆襲 - part1Yi-Feng Tzeng
 
REST API Design & Development
REST API Design & DevelopmentREST API Design & Development
REST API Design & DevelopmentAshok Pundit
 
Come Fly With Me: Database Migration Patterns with Flyway
Come Fly With Me: Database Migration Patterns with FlywayCome Fly With Me: Database Migration Patterns with Flyway
Come Fly With Me: Database Migration Patterns with FlywayJoris Kuipers
 

Tendances (20)

Introduction to DataFusion An Embeddable Query Engine Written in Rust
Introduction to DataFusion  An Embeddable Query Engine Written in RustIntroduction to DataFusion  An Embeddable Query Engine Written in Rust
Introduction to DataFusion An Embeddable Query Engine Written in Rust
 
Schema Evolution for Resilient Data microservices
Schema Evolution for Resilient Data microservicesSchema Evolution for Resilient Data microservices
Schema Evolution for Resilient Data microservices
 
How to Use JSON in MySQL Wrong
How to Use JSON in MySQL WrongHow to Use JSON in MySQL Wrong
How to Use JSON in MySQL Wrong
 
Building Fullstack Serverless GraphQL APIs In The Cloud
Building Fullstack Serverless GraphQL APIs In The CloudBuilding Fullstack Serverless GraphQL APIs In The Cloud
Building Fullstack Serverless GraphQL APIs In The Cloud
 
How to Design Indexes, Really
How to Design Indexes, ReallyHow to Design Indexes, Really
How to Design Indexes, Really
 
OLTP+OLAP=HTAP
 OLTP+OLAP=HTAP OLTP+OLAP=HTAP
OLTP+OLAP=HTAP
 
Apache NiFi Record Processing
Apache NiFi Record ProcessingApache NiFi Record Processing
Apache NiFi Record Processing
 
How to understand and analyze Apache Hive query execution plan for performanc...
How to understand and analyze Apache Hive query execution plan for performanc...How to understand and analyze Apache Hive query execution plan for performanc...
How to understand and analyze Apache Hive query execution plan for performanc...
 
Data Storage Tips for Optimal Spark Performance-(Vida Ha, Databricks)
Data Storage Tips for Optimal Spark Performance-(Vida Ha, Databricks)Data Storage Tips for Optimal Spark Performance-(Vida Ha, Databricks)
Data Storage Tips for Optimal Spark Performance-(Vida Ha, Databricks)
 
Espresso: LinkedIn's Distributed Data Serving Platform (Paper)
Espresso: LinkedIn's Distributed Data Serving Platform (Paper)Espresso: LinkedIn's Distributed Data Serving Platform (Paper)
Espresso: LinkedIn's Distributed Data Serving Platform (Paper)
 
Optimizing Hive Queries
Optimizing Hive QueriesOptimizing Hive Queries
Optimizing Hive Queries
 
Adobe Behance Scales to Millions of Users at Lower TCO with Neo4j
Adobe Behance Scales to Millions of Users at Lower TCO with Neo4jAdobe Behance Scales to Millions of Users at Lower TCO with Neo4j
Adobe Behance Scales to Millions of Users at Lower TCO with Neo4j
 
Mysql Optimization
Mysql OptimizationMysql Optimization
Mysql Optimization
 
Introduction to the Web API
Introduction to the Web APIIntroduction to the Web API
Introduction to the Web API
 
Graphql Intro (Tutorial and Example)
Graphql Intro (Tutorial and Example)Graphql Intro (Tutorial and Example)
Graphql Intro (Tutorial and Example)
 
Apache Druid 101
Apache Druid 101Apache Druid 101
Apache Druid 101
 
Parquet performance tuning: the missing guide
Parquet performance tuning: the missing guideParquet performance tuning: the missing guide
Parquet performance tuning: the missing guide
 
善用 MySQL 及 PostgreSQL - RDBMS 的逆襲 - part1
善用 MySQL 及 PostgreSQL - RDBMS 的逆襲 - part1善用 MySQL 及 PostgreSQL - RDBMS 的逆襲 - part1
善用 MySQL 及 PostgreSQL - RDBMS 的逆襲 - part1
 
REST API Design & Development
REST API Design & DevelopmentREST API Design & Development
REST API Design & Development
 
Come Fly With Me: Database Migration Patterns with Flyway
Come Fly With Me: Database Migration Patterns with FlywayCome Fly With Me: Database Migration Patterns with Flyway
Come Fly With Me: Database Migration Patterns with Flyway
 

Similaire à How to name things: the hardest problem in programming

How to write maintainable code - Peter Hilton - Codemotion Amsterdam 2017
How to write maintainable code - Peter Hilton - Codemotion Amsterdam 2017How to write maintainable code - Peter Hilton - Codemotion Amsterdam 2017
How to write maintainable code - Peter Hilton - Codemotion Amsterdam 2017Codemotion
 
How to write maintainable code
How to write maintainable codeHow to write maintainable code
How to write maintainable codePeter Hilton
 
Naming guidelines for professional programmers
Naming guidelines for professional programmersNaming guidelines for professional programmers
Naming guidelines for professional programmersPeter Hilton
 
Ewrt 1 a class 5
Ewrt 1 a class 5Ewrt 1 a class 5
Ewrt 1 a class 5kimpalmore
 
Plagiarism and paraphrasing
Plagiarism and paraphrasingPlagiarism and paraphrasing
Plagiarism and paraphrasingAnkita Kunwar
 
EAPP LESSON 2 SUMMARIZING AND PARAPHRASING.pdf
EAPP LESSON 2 SUMMARIZING AND PARAPHRASING.pdfEAPP LESSON 2 SUMMARIZING AND PARAPHRASING.pdf
EAPP LESSON 2 SUMMARIZING AND PARAPHRASING.pdfMaryJoyFrondoza
 
Solving for ambiguity: what the data literate can learn from the design process
Solving for ambiguity: what the data literate can learn from the design processSolving for ambiguity: what the data literate can learn from the design process
Solving for ambiguity: what the data literate can learn from the design processDean Malmgren
 
Ewrt 1 a plus hybrid week 3
Ewrt 1 a plus  hybrid week 3Ewrt 1 a plus  hybrid week 3
Ewrt 1 a plus hybrid week 3kimpalmore
 
Getting a job in industry
Getting a job in industryGetting a job in industry
Getting a job in industryAustin Baird
 
COPYREADING-AND-HEADLINE-WRITING-2017.pptx
COPYREADING-AND-HEADLINE-WRITING-2017.pptxCOPYREADING-AND-HEADLINE-WRITING-2017.pptx
COPYREADING-AND-HEADLINE-WRITING-2017.pptxLeaLace
 
API Simplicity == Speed; Designing APIs That are Easy and Fun to Use
API Simplicity == Speed; Designing APIs That are Easy and Fun to UseAPI Simplicity == Speed; Designing APIs That are Easy and Fun to Use
API Simplicity == Speed; Designing APIs That are Easy and Fun to UseHarold Madsen
 
Peer edit project
Peer edit projectPeer edit project
Peer edit projectjsnart
 

Similaire à How to name things: the hardest problem in programming (20)

How to write maintainable code - Peter Hilton - Codemotion Amsterdam 2017
How to write maintainable code - Peter Hilton - Codemotion Amsterdam 2017How to write maintainable code - Peter Hilton - Codemotion Amsterdam 2017
How to write maintainable code - Peter Hilton - Codemotion Amsterdam 2017
 
How to write maintainable code
How to write maintainable codeHow to write maintainable code
How to write maintainable code
 
Naming guidelines for professional programmers
Naming guidelines for professional programmersNaming guidelines for professional programmers
Naming guidelines for professional programmers
 
Ewrt 1 a class 5
Ewrt 1 a class 5Ewrt 1 a class 5
Ewrt 1 a class 5
 
Introduction to ChatGPT
Introduction to ChatGPTIntroduction to ChatGPT
Introduction to ChatGPT
 
Plagiarism and paraphrasing
Plagiarism and paraphrasingPlagiarism and paraphrasing
Plagiarism and paraphrasing
 
EAPP LESSON 2 SUMMARIZING AND PARAPHRASING.pdf
EAPP LESSON 2 SUMMARIZING AND PARAPHRASING.pdfEAPP LESSON 2 SUMMARIZING AND PARAPHRASING.pdf
EAPP LESSON 2 SUMMARIZING AND PARAPHRASING.pdf
 
Solving for ambiguity: what the data literate can learn from the design process
Solving for ambiguity: what the data literate can learn from the design processSolving for ambiguity: what the data literate can learn from the design process
Solving for ambiguity: what the data literate can learn from the design process
 
Os Goodger
Os GoodgerOs Goodger
Os Goodger
 
Ewrt 1 a plus hybrid week 3
Ewrt 1 a plus  hybrid week 3Ewrt 1 a plus  hybrid week 3
Ewrt 1 a plus hybrid week 3
 
Getting a job in industry
Getting a job in industryGetting a job in industry
Getting a job in industry
 
D10-EWRT 211
D10-EWRT 211D10-EWRT 211
D10-EWRT 211
 
FOJ Lectures
FOJ LecturesFOJ Lectures
FOJ Lectures
 
D5-EWRT 1A
D5-EWRT 1AD5-EWRT 1A
D5-EWRT 1A
 
COPYREADING-AND-HEADLINE-WRITING-2017.pptx
COPYREADING-AND-HEADLINE-WRITING-2017.pptxCOPYREADING-AND-HEADLINE-WRITING-2017.pptx
COPYREADING-AND-HEADLINE-WRITING-2017.pptx
 
API Simplicity == Speed; Designing APIs That are Easy and Fun to Use
API Simplicity == Speed; Designing APIs That are Easy and Fun to UseAPI Simplicity == Speed; Designing APIs That are Easy and Fun to Use
API Simplicity == Speed; Designing APIs That are Easy and Fun to Use
 
The Emperor Has No Docs (Geecon Oct'23)
The Emperor Has No Docs (Geecon Oct'23)The Emperor Has No Docs (Geecon Oct'23)
The Emperor Has No Docs (Geecon Oct'23)
 
Finding a critical thinker
Finding a critical thinkerFinding a critical thinker
Finding a critical thinker
 
Peer edit project
Peer edit projectPeer edit project
Peer edit project
 
Apex for humans
Apex for humansApex for humans
Apex for humans
 

Plus de Peter Hilton

E-Prime: English for scientific writing
E-Prime: English for scientific writing E-Prime: English for scientific writing
E-Prime: English for scientific writing Peter Hilton
 
Process-oriented reactive service architecture
Process-oriented reactive service architectureProcess-oriented reactive service architecture
Process-oriented reactive service architecturePeter Hilton
 
HTTP demystified for web developers
HTTP demystified for web developersHTTP demystified for web developers
HTTP demystified for web developersPeter Hilton
 
Documentation avoidance for developers
Documentation avoidance for developersDocumentation avoidance for developers
Documentation avoidance for developersPeter Hilton
 
Meeting-avoidance for self-managing developers
Meeting-avoidance for self-managing developersMeeting-avoidance for self-managing developers
Meeting-avoidance for self-managing developersPeter Hilton
 
How to write good comments
How to write good commentsHow to write good comments
How to write good commentsPeter Hilton
 
Scaling business app development with Play and Scala
Scaling business app development with Play and ScalaScaling business app development with Play and Scala
Scaling business app development with Play and ScalaPeter Hilton
 
Play framework: lessons learned
Play framework: lessons learnedPlay framework: lessons learned
Play framework: lessons learnedPeter Hilton
 

Plus de Peter Hilton (9)

Beautiful code
Beautiful codeBeautiful code
Beautiful code
 
E-Prime: English for scientific writing
E-Prime: English for scientific writing E-Prime: English for scientific writing
E-Prime: English for scientific writing
 
Process-oriented reactive service architecture
Process-oriented reactive service architectureProcess-oriented reactive service architecture
Process-oriented reactive service architecture
 
HTTP demystified for web developers
HTTP demystified for web developersHTTP demystified for web developers
HTTP demystified for web developers
 
Documentation avoidance for developers
Documentation avoidance for developersDocumentation avoidance for developers
Documentation avoidance for developers
 
Meeting-avoidance for self-managing developers
Meeting-avoidance for self-managing developersMeeting-avoidance for self-managing developers
Meeting-avoidance for self-managing developers
 
How to write good comments
How to write good commentsHow to write good comments
How to write good comments
 
Scaling business app development with Play and Scala
Scaling business app development with Play and ScalaScaling business app development with Play and Scala
Scaling business app development with Play and Scala
 
Play framework: lessons learned
Play framework: lessons learnedPlay framework: lessons learned
Play framework: lessons learned
 

Dernier

Fields in Java and Kotlin and what to expect.pptx
Fields in Java and Kotlin and what to expect.pptxFields in Java and Kotlin and what to expect.pptx
Fields in Java and Kotlin and what to expect.pptxJoão Esperancinha
 
Top Software Development Trends in 2024
Top Software Development Trends in  2024Top Software Development Trends in  2024
Top Software Development Trends in 2024Mind IT Systems
 
Introduction-to-Software-Development-Outsourcing.pptx
Introduction-to-Software-Development-Outsourcing.pptxIntroduction-to-Software-Development-Outsourcing.pptx
Introduction-to-Software-Development-Outsourcing.pptxIntelliSource Technologies
 
Growing Oxen: channel operators and retries
Growing Oxen: channel operators and retriesGrowing Oxen: channel operators and retries
Growing Oxen: channel operators and retriesSoftwareMill
 
Your Vision, Our Expertise: TECUNIQUE's Tailored Software Teams
Your Vision, Our Expertise: TECUNIQUE's Tailored Software TeamsYour Vision, Our Expertise: TECUNIQUE's Tailored Software Teams
Your Vision, Our Expertise: TECUNIQUE's Tailored Software TeamsJaydeep Chhasatia
 
Enterprise Document Management System - Qualityze Inc
Enterprise Document Management System - Qualityze IncEnterprise Document Management System - Qualityze Inc
Enterprise Document Management System - Qualityze Incrobinwilliams8624
 
Kawika Technologies pvt ltd Software Development Company in Trivandrum
Kawika Technologies pvt ltd Software Development Company in TrivandrumKawika Technologies pvt ltd Software Development Company in Trivandrum
Kawika Technologies pvt ltd Software Development Company in TrivandrumKawika Technologies
 
Leveraging DxSherpa's Generative AI Services to Unlock Human-Machine Harmony
Leveraging DxSherpa's Generative AI Services to Unlock Human-Machine HarmonyLeveraging DxSherpa's Generative AI Services to Unlock Human-Machine Harmony
Leveraging DxSherpa's Generative AI Services to Unlock Human-Machine Harmonyelliciumsolutionspun
 
online pdf editor software solutions.pdf
online pdf editor software solutions.pdfonline pdf editor software solutions.pdf
online pdf editor software solutions.pdfMeon Technology
 
Webinar_050417_LeClair12345666777889.ppt
Webinar_050417_LeClair12345666777889.pptWebinar_050417_LeClair12345666777889.ppt
Webinar_050417_LeClair12345666777889.pptkinjal48
 
ERP For Electrical and Electronics manufecturing.pptx
ERP For Electrical and Electronics manufecturing.pptxERP For Electrical and Electronics manufecturing.pptx
ERP For Electrical and Electronics manufecturing.pptxAutus Cyber Tech
 
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.Sharon Liu
 
JS-Experts - Cybersecurity for Generative AI
JS-Experts - Cybersecurity for Generative AIJS-Experts - Cybersecurity for Generative AI
JS-Experts - Cybersecurity for Generative AIIvo Andreev
 
Watermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security ChallengesWatermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security ChallengesShyamsundar Das
 
eAuditor Audits & Inspections - conduct field inspections
eAuditor Audits & Inspections - conduct field inspectionseAuditor Audits & Inspections - conduct field inspections
eAuditor Audits & Inspections - conduct field inspectionsNirav Modi
 
Generative AI for Cybersecurity - EC-Council
Generative AI for Cybersecurity - EC-CouncilGenerative AI for Cybersecurity - EC-Council
Generative AI for Cybersecurity - EC-CouncilVICTOR MAESTRE RAMIREZ
 
Sales Territory Management: A Definitive Guide to Expand Sales Coverage
Sales Territory Management: A Definitive Guide to Expand Sales CoverageSales Territory Management: A Definitive Guide to Expand Sales Coverage
Sales Territory Management: A Definitive Guide to Expand Sales CoverageDista
 
Why Choose Brain Inventory For Ecommerce Development.pdf
Why Choose Brain Inventory For Ecommerce Development.pdfWhy Choose Brain Inventory For Ecommerce Development.pdf
Why Choose Brain Inventory For Ecommerce Development.pdfBrain Inventory
 
AI Embracing Every Shade of Human Beauty
AI Embracing Every Shade of Human BeautyAI Embracing Every Shade of Human Beauty
AI Embracing Every Shade of Human BeautyRaymond Okyere-Forson
 

Dernier (20)

Fields in Java and Kotlin and what to expect.pptx
Fields in Java and Kotlin and what to expect.pptxFields in Java and Kotlin and what to expect.pptx
Fields in Java and Kotlin and what to expect.pptx
 
Top Software Development Trends in 2024
Top Software Development Trends in  2024Top Software Development Trends in  2024
Top Software Development Trends in 2024
 
Introduction-to-Software-Development-Outsourcing.pptx
Introduction-to-Software-Development-Outsourcing.pptxIntroduction-to-Software-Development-Outsourcing.pptx
Introduction-to-Software-Development-Outsourcing.pptx
 
Growing Oxen: channel operators and retries
Growing Oxen: channel operators and retriesGrowing Oxen: channel operators and retries
Growing Oxen: channel operators and retries
 
Your Vision, Our Expertise: TECUNIQUE's Tailored Software Teams
Your Vision, Our Expertise: TECUNIQUE's Tailored Software TeamsYour Vision, Our Expertise: TECUNIQUE's Tailored Software Teams
Your Vision, Our Expertise: TECUNIQUE's Tailored Software Teams
 
Enterprise Document Management System - Qualityze Inc
Enterprise Document Management System - Qualityze IncEnterprise Document Management System - Qualityze Inc
Enterprise Document Management System - Qualityze Inc
 
Kawika Technologies pvt ltd Software Development Company in Trivandrum
Kawika Technologies pvt ltd Software Development Company in TrivandrumKawika Technologies pvt ltd Software Development Company in Trivandrum
Kawika Technologies pvt ltd Software Development Company in Trivandrum
 
Leveraging DxSherpa's Generative AI Services to Unlock Human-Machine Harmony
Leveraging DxSherpa's Generative AI Services to Unlock Human-Machine HarmonyLeveraging DxSherpa's Generative AI Services to Unlock Human-Machine Harmony
Leveraging DxSherpa's Generative AI Services to Unlock Human-Machine Harmony
 
Salesforce AI Associate Certification.pptx
Salesforce AI Associate Certification.pptxSalesforce AI Associate Certification.pptx
Salesforce AI Associate Certification.pptx
 
online pdf editor software solutions.pdf
online pdf editor software solutions.pdfonline pdf editor software solutions.pdf
online pdf editor software solutions.pdf
 
Webinar_050417_LeClair12345666777889.ppt
Webinar_050417_LeClair12345666777889.pptWebinar_050417_LeClair12345666777889.ppt
Webinar_050417_LeClair12345666777889.ppt
 
ERP For Electrical and Electronics manufecturing.pptx
ERP For Electrical and Electronics manufecturing.pptxERP For Electrical and Electronics manufecturing.pptx
ERP For Electrical and Electronics manufecturing.pptx
 
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.
20240319 Car Simulator Plan.pptx . Plan for a JavaScript Car Driving Simulator.
 
JS-Experts - Cybersecurity for Generative AI
JS-Experts - Cybersecurity for Generative AIJS-Experts - Cybersecurity for Generative AI
JS-Experts - Cybersecurity for Generative AI
 
Watermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security ChallengesWatermarking in Source Code: Applications and Security Challenges
Watermarking in Source Code: Applications and Security Challenges
 
eAuditor Audits & Inspections - conduct field inspections
eAuditor Audits & Inspections - conduct field inspectionseAuditor Audits & Inspections - conduct field inspections
eAuditor Audits & Inspections - conduct field inspections
 
Generative AI for Cybersecurity - EC-Council
Generative AI for Cybersecurity - EC-CouncilGenerative AI for Cybersecurity - EC-Council
Generative AI for Cybersecurity - EC-Council
 
Sales Territory Management: A Definitive Guide to Expand Sales Coverage
Sales Territory Management: A Definitive Guide to Expand Sales CoverageSales Territory Management: A Definitive Guide to Expand Sales Coverage
Sales Territory Management: A Definitive Guide to Expand Sales Coverage
 
Why Choose Brain Inventory For Ecommerce Development.pdf
Why Choose Brain Inventory For Ecommerce Development.pdfWhy Choose Brain Inventory For Ecommerce Development.pdf
Why Choose Brain Inventory For Ecommerce Development.pdf
 
AI Embracing Every Shade of Human Beauty
AI Embracing Every Shade of Human BeautyAI Embracing Every Shade of Human Beauty
AI Embracing Every Shade of Human Beauty
 

How to name things: the hardest problem in programming

  • 1. @PeterHilton http://hilton.org.uk/ the hardest problem in programming How to name things:
  • 2. 15 years as 
 the dev team’s only native English speaker… @PeterHilton • 2
  • 5. How to name things, by G. Orwell ‘What is above all needed is to 
 let the meaning choose the word, 
 and not the other way around. … the worst thing one can do with words is surrender to them.
  • 6. ‘When you think of a concrete object, you think wordlessly, and then, if you want to describe the thing you have been visualising you probably hunt about until you find the exact words that seem to fit it.
  • 7. ‘When you think of something abstract you are more inclined to use words from the start, and unless you make a conscious effort to prevent it, the existing dialect will come rushing in and do the job for you, at the expense of blurring or even changing your meaning…
  • 8. 1. Never use a metaphor, simile, or other figure of speech which you are used to seeing in print. 2. Never use a long word where a short one will do. 3. If it is possible to cut a word out, always cut it out. 4. Never use the passive where you can use the active. 5. Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent. 6. Break any of these rules sooner than say anything outright barbarous.
  • 9. ‘These rules sound elementary, and so they are, but they demand a deep change of attitude in anyone who has grown used to writing in the style now fashionable.’
  • 10. Politics and the English Language
 (1946)
  • 11. 1. ‘Never use a metaphor, simile, or other figure of speech which you are used to seeing in print’ (beware of over-using design patterns, and using their names just because you’re used to seeing them in code) e.g. AbstractConfigurationFactory 11@PeterHilton •
  • 12. 2. ‘Never use a long word 
 where a short one will do’ (prefer concise variable names, 
 use longer names for a good reason) e.g. company_person_collection   vs staff 12@PeterHilton •
  • 13. 3. ‘If it is possible to cut a word out, always cut it out’ (avoid additional words that don’t add any meaning to a name) e.g. AbstractObjectFormatterProxy   … 13@PeterHilton •
  • 14. AbstractAnnotationConfigDispatcher ServletInitializer   14@PeterHilton • org.springframework.web.servlet.support. ‘This is like homeopathy. 
 What you’ve done is you’ve diluted the meaning until it’s all gone.’ @KevlinHenney
  • 15. 4. ‘Never use the passive 
 where you can use the active’ (respect grammatical rules for identifiers) e.g. class  PlanEvents   vs class  EventPlanner   or even class  Scheduler   15@PeterHilton •
  • 16. 5. ‘Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent’ (don’t let technical jargon from a library pollute your domain model) (beware libraries that import ‘foreign’ naming from one language to another) e.g. ShipmentMonad 16@PeterHilton •
  • 17. 6. ‘Break any of these rules sooner than say anything outright barbarous’ (don’t blame me if your code is featured on The Daily WTF) Note: a lot depends on context; publishing library code is not the same as maintaining private application code 17@PeterHilton •
  • 18. It sounds like writing prose 
 is as hard as 
 writing code. Who knew? @PeterHilton • 18
  • 21. 21 ‘Write with the 
 door closed, 
 rewrite with the 
 door open.’ Stephen King on pair programming @PeterHilton •
  • 22. warriorwoman531 / CC BY-ND 2.0
  • 23. 23 Anne Rice on development hardware ‘I find the bigger 
 the monitor, 
 the better the concentration.’ @PeterHilton •
  • 25. Ernest Hemingway on user personas ‘When writing a novel a writer should create living people; 
 people not characters. 
 A character is a caricature.’ 25@PeterHilton •
  • 27. W. Somerset Maugham on 
 enterprise architecture ‘There are three rules for writing the novel. Unfortunately, no one knows what they are.’ 27@PeterHilton •
  • 28. ranh / CC BY 2.0
  • 29. Neil Gaiman on productivity ‘Write.
 
 ‘Put one word after another. 
 Find the right word, put it down. 
 ‘Finish what you’re writing. Whatever you have to do to finish it, finish it.’ 29@PeterHilton •
  • 30. Neil Gaiman on code review ‘Put it aside. Read it pretending you’ve never read it before. Show it to friends whose opinion you respect’ 30@PeterHilton •
  • 31. Neil Gaiman on review feedback ‘When people tell you something’s wrong or doesn’t work for them, they are almost always right.
 
 ‘When they tell you exactly what they think is wrong and how to fix it, they are almost always wrong.’ 31@PeterHilton •
  • 32. Neil Gaiman on refactoring ‘Fix it. ‘Remember that, sooner or later, before it ever reaches perfection, you will have to let it go and move on and start to write the next thing. ‘Perfection is like chasing the horizon. 
 Keep moving.’ 32@PeterHilton •
  • 33. Neil Gaiman on humour in code ‘Laugh at your own jokes.’ 33@PeterHilton •
  • 34. Neil Gaiman on open source ‘The main rule of writing is that if you do it with enough assurance and confidence, you’re allowed to do whatever you like.’ 34@PeterHilton •
  • 35. Summary of advice from writers Advice from writers is useful, and 
 not only about naming. Writers have been at it for centuries; programming is merely decades old. Also, their advice is better written.
 And funnier. 35@PeterHilton •
  • 36. Getting it right means a struggle for every single word. @PeterHilton • 36
  • 38. Phil Karlton on naming ‘There are only two hard things 
 in Computer Science: 
 1. cache invalidation and 2. naming things.’ 38@PeterHilton • 0. off-by-one errors
  • 39. Lewis Carroll on bad naming ‘When I use a word,’ Humpty Dumpty said, in rather a scornful tone, ‘it means just what I choose it to mean - neither more nor less.’ Through the Looking-Glass, 
 and What Alice Found There (1871) 39@PeterHilton •
  • 40. Deliberately meaningless names In theory, foo is only used as a placeholder name (because it doesn’t mean anything) 40@PeterHilton •
  • 41. Sam Gardiner on naming ‘If you don’t know what a thing should be called, you cannot know what it is. If you don’t know what it is, you cannot sit down and write the code.’ http://97things.oreilly.com/wiki/index.php/ A_rose_by_any_other_name_will_end_up_as_a_cabbage 41@PeterHilton •
  • 42. What is the worst ever
 variable name? data   What is the second-worst name? data2   What is the third-worst name ever? data_2 42@PeterHilton •
  • 43. Abbreviations are ambiguous Is char a character or characteristic? Does mod mean modify or modulo? What about acc, pos or auth? Sadly, fab was just a function ƒ:A➞B
 (not fabulous) Allow one exception: id for ‘identity’ 43@PeterHilton •
  • 44. One letter is too short Local variable: what is the meaning? var  a  =  42;   The exception that proves the rule? for  (int  i  =  1;  i  <  42;  ++i)   Not an improvement: 
 ii, jj, kk 44@PeterHilton •
  • 45. Functional programming:
 one letter is still too short 45@PeterHilton • def  modp[C]
        (f:  B1    (B2,  C),  a:  A1):  
        (A2,  C)  =  {      val  (b,  c)  =  f(get(a))      (set(a,  b),  c)   }   https://github.com/scalaz/scalaz/blob/series/7.2.x/core/src/main/scala/scalaz/Lens.scala
  • 50. Multiple words can be replaced by more specific words What’s an appointment_list? a calendar   What’s an company_person? an employee or perhaps an owner   What’s a text_correction_by_editor? just an edit 50@PeterHilton •
  • 51. Vague words are vague 51@PeterHilton • Alan Green wrote* about vague words, e.g. InvoiceManager   TaskManager   ‘Manager’ is very imprecise; one of its meanings may be the word you want: Bucket, Supervisor, Planner, Builder * http://www.bright-green.com/blog/2003_02_25/naming_java_classes_without_a.html
  • 52. Vague words are vague 52@PeterHilton • get at the start of a method name is
 appropriate only for returning a field value. If it does anything else, or gets the data from anywhere else, use another name: fetch, find, lookup, create, calculate, derive, concoct,
  • 53. Wrong words are wrong, Synonyms are confusing order ≠ shipment carrier ≠ broker shipment ≠ transport leg shipment = consignment carrier = transporter transport leg = journey 53@PeterHilton •
  • 54. Apache Camel - http://camel.apache.org (Java enterprise 
 middleware example)
  • 55. //  Not  enough  jokes  in  code   /**  Configure  and  start  Apache  Camel.  */   {      Logger.info("Starting  Camel…")      val  context  =  new  DefaultCamelContext()      configuredRoutes  foreach  {  route  =>  
      context.addRoutes(route)
    }      context.start()   } def  mountCamel()  {
  • 57. Property accessors revisited In a numeric library, these method names would be irresistible, but inadvisable: getEven   getReal   getAround   getRoundTo   getRichQuick   getJoke 57@PeterHilton •
  • 58. Summary of naming things badly Meaningless: foo Too general: data Too short: a Too long: text_correction_by_editor   Abbreviated: acc   Vague: InvoiceManager   Wrong: order   Just not funny: startCamel 58@PeterHilton •
  • 60. How to solve the naming problem Become a better writer. Improve your vocabulary. Adopt better naming practices. Work on it. 60@PeterHilton •
  • 61. Become a better writer Naming is just one part of writing, and is mostly about vocabulary. You may remember working on vocabulary as part of learning a foreign language. Not having had to learn a foreign language is a mixed blessing. 61@PeterHilton •
  • 62. Improve your general vocabulary Read books, especially funny novels. Play word games with someone who always wins, until they don’t. 62@PeterHilton •
  • 65. Improve your general vocabulary Use your dictionary and thesaurus… 65@PeterHilton •
  • 67. @PeterHilton • 67 A sandwich walks into a pub. The barman says,
 ‘I’m sorry, we don’t serve food.’
  • 68. Tell jokes Many jokes rely on word-play. It takes practice to think of puns quickly. Puns are important for naming, because they rely on double-meanings. Spotting double-meanings is the essential skill for avoiding ambiguous names. 68@PeterHilton •
  • 69. Adopt better naming practices 69@PeterHilton • Start with meaning and intention. Use words with precise meanings. Prefer fewer words in names. No abbreviations in names, except id. Use code review to improve names. Remember: ‘rename’ is the simplest but most effective refactoring. Use it.
  • 70. Replace vague words with more specific synonyms Manager   Object   Data   Thing   Info   Amount   Details
 do   execute   perform   operate   manage   handle   get 70@PeterHilton •
  • 71. Overcome fear of renaming The only thing harder than naming is renaming. Renaming requires change, a conversation, and new understanding. ‘Refactor’ is the safest refactoring. 71@PeterHilton •
  • 72. Chapter 10: The power of variable names
  • 75. Gather domain-specific vocabulary Scan the domain model entities’ Wikipedia pages for names of related concepts. Read novels set in your customer’s domain, to learn their jargon. Find out what they really mean. 75@PeterHilton •
  • 79. Programmers Stack Exchange - question by Tragedian answered by gnat / CC-BY-SA For naming, there are six techniques that were proven to work for me: 1. spend a lot of time on inventing names 2. use code reviews 3. don’t hesitate to rename 4. spend a lot of time on inventing names 5. use code reviews 6. don’t hesitate to rename
  • 80. Additional benefits If you become a better writer, you could use your new skills … for writing 80@PeterHilton •
  • 82. ‘Most of the things programmers say about comments in code are excuses for not writing any comments at all.’ @PeterHilton 82@PeterHilton •
  • 83. Comments: the basics 1. Don’t say what the code does
 (because the code already says that) 2. Don’t explain awkward logic
 (improve the code to make it clear) 3. Don’t add too many comments
 (it’s messy and they’ll get out of date) 83@PeterHilton •
  • 84. Explain why the code exists Even perfect code cannot explain its own existence. When should I use this code? When shouldn’t I use it? What are the alternatives to this code? 84@PeterHilton •
  • 85. Discover which comments are hard to write, and why If a comment is easy to write, then that code doesn’t need a comment. Write a one-sentence comment, for 
 every class and method, to start with. 85@PeterHilton •
  • 86. ‘A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments.’ @KevlinHenney 86@PeterHilton •
  • 87. Acknowledge that writing (comments) is a specialist skill On a cross-functional development team, not everyone is good at visual design. The same goes for writing about code. Work out who is a better writer. Get help with writing comments. 87@PeterHilton •
  • 88. How to write good comments (summary) 1. Try to write good code first. 2. Try to write a one-sentence comment. 3. Refactor the code until the comment is easy to write. 4. Now write a good comment. 5. Don’t forget the rules of good writing (e.g. remove unnecessary comments). 88@PeterHilton •
  • 90. Summary 1. Naming is hard 2. Get inspiration from great writers 3. Read novels, tell jokes, play games 4. Expand your vocabulary 5. Try actual writing; 
 start with comments,
 try blogging, or even write a book 90@PeterHilton •
  • 91. @PeterHilton http://hilton.org.uk/ Peter Hilton is available for company and conference presentations peter.hilton@gmail.com