I get frustrated with code that is sprinkled with poorly named classes, methods, and variables. Whenever I work on a team or coach a team, I put a lot of energy into choosing good names and sensitizing my teammates to the power of naming. I've noticed that developers spend most of their days reading code rather than writing code. I suspect you've noticed too. Creating understandable code is a high leverage activity for any team. And naming is where I start. Simple Design. Domain-Driven Design.

1. Don’t Settle for
Poor Names
Alistair McKinnell
@amckinnell

2. Naming
is deeply
connected to
Designing

3. Designing
is deeply
connected to
Naming

4. Example from
QCloud

5. QCloud has forms,
sheets, and inspections

6. QCloud has forms,
sheets, and inspections

13. A sheet is composed of a
reviewed and a submitted
{ something or other }

15. class Sheet < ActiveRecord::Base
composed_of :submitted_attribution_event,
class_name: ’AttributionEvent',
allow_nil: true,
mapping: [
['submitted_by_name', 'name'],
['submitted_by_email', 'email'],
['submitted_by_id', 'user_id'],
['submitted_at', 'event_at']
]
composed_of :reviewed_attribution_event,
class_name: 'AttributionEvent',
allow_nil: true,
mapping: [
['reviewed_by_name', 'name'],
['reviewed_by_email', 'email'],
['reviewed_by_id', 'user_id'],
['reviewed_at', 'event_at']
]

16. #
# Represents the information required to attribute
# an event to a user.
#
class AttributionEvent
attr_reader :name, :email, :user_id, :event_at
def initialize(name, email, user_id, at)
@name = name
@email = email
@user_id = user_id
@event_at = at
end
end
composed_of :submitted_attribution_event,
class_name: ’AttributionEvent',
allow_nil: true,
mapping: [
['submitted_by_name', 'name'],
['submitted_by_email', 'email'],
['submitted_by_id', 'user_id'],
['submitted_at', 'event_at']
]

17. A sheet is composed of a
reviewed and a submitted
attribution event

18. An attribution event
identifies a user and
has a timestamp

19. An attribution event
identifies a user and
has a timestamp

20. An attribution event
identifies a user and
has a timestamp

21. #
# Represents the information required to attribute
# an event to a user.
#
class AttributionEvent
attr_reader :name, :email, :user_id, :event_at
def initialize(name, email, user_id, at)
@name = name
@email = email
@user_id = user_id
@event_at = at
end
end
An attribution event
identifies a user and
has a timestamp

22. sheet.submitted_attribution_event =
AttributionEvent.new(
inspector.name, inspector.email,
inspector.id, Time.zone.now
)
sheet.submitted_by_name = inspector.name
sheet.submitted_by_email = inspector.email
sheet.submitted_by_id = inspector.id
sheet.submitted_at = Time.zone.now
Before
After

23. sheet.submitted_attribution_event =
AttributionEvent.new(
inspector.name, inspector.email,
inspector.id, Time.zone.now
)
sheet.submitted_by_name = inspector.name
sheet.submitted_by_email = inspector.email
sheet.submitted_by_id = inspector.id
sheet.submitted_at = Time.zone.now
Before
After

24. #
# Represents the information required to attribute
# an event to a user.
#
class AttributionEvent
attr_reader :name, :email, :user_id, :event_at
def initialize(name, email, user_id, at)
@name = name
@email = email
@user_id = user_id
@event_at = at
end
end
An attribution event
identifies a user and
has a timestamp

25. #
# Represents the information required to attribute
# an event to a user.
#
class AttributionEvent
attr_reader :name, :email, :user_id, :event_at
def self.build(user, at: Time.zone.now)
new(user.name, user.email, user.id, at)
end
def initialize(name, email, user_id, at)
@name = name
@email = email
@user_id = user_id
@event_at = at
end
end
An attribution event
identifies a user and
has a timestamp

26. sheet.submitted_attribution_event =
AttributionEvent.build(inspector)
sheet.submitted_by_name = inspector.name
sheet.submitted_by_email = inspector.email
sheet.submitted_by_id = inspector.id
sheet.submitted_at = Time.zone.now
Before
After

27. sheet.submitted_attribution_event =
AttributionEvent.build(inspector)
sheet.submitted_by_name = inspector.name
sheet.submitted_by_id = inspector.id
sheet.submitted_at = Time.zone.now
Before
After
!

28. sheet.submitted_attribution_event =
AttributionEvent.build(inspector)
sheet.submitted_by_name = inspector.name
sheet.submitted_by_email = inspector.email
sheet.submitted_by_id = inspector.id
sheet.submitted_at = Time.zone.now
Before
After

29. sheet.submitted_attribution_event =
AttributionEvent.build(inspector)
sheet.submitted_by_name = inspector.name
sheet.submitted_by_email = reviewer.email
sheet.submitted_by_id = inspector.id
sheet.submitted_at = Time.zone.now
Before
After
!

30. sheet.submitted_attribution_event =
AttributionEvent.build(inspector)
sheet.submitted_by_name = inspector.name
sheet.submitted_by_email = reviewer.email
sheet.submitted_by_id = inspector.id
sheet.submitted_at = Time.zone.now
Before
After

31. #
# Represents the information required to attribute
# an event to a user.
#
class AttributionEvent
attr_reader :name, :email, :user_id, :event_at
def self.build(user, at: Time.zone.now)
new(user.name, user.email, user.id, at)
end
def initialize(name, email, user_id, at)
@name = name
@email = email
@user_id = user_id
@event_at = at
end
end

32. class Sheet < ActiveRecord::Base
composed_of :reviewed_attribution_event,
class_name: 'AttributionEvent',
allow_nil: true,
mapping: [
['reviewed_by_name', 'name'],
['reviewed_by_email', 'email'],
['reviewed_by_id', 'user_id'],
['reviewed_at', 'event_at']
]
composed_of :submitted_attribution_event,
class_name: ’AttributionEvent',
allow_nil: true,
mapping: [
['submitted_by_name', 'name'],
['submitted_by_email', 'email'],
['submitted_by_id', 'user_id'],
['submitted_at', 'event_at']
]

33. class Sheet < ActiveRecord::Base
composed_of :reviewed_attribution_event,
class_name: ’AttributionEvent',
allow_nil: true,
mapping: [
[‘reviewed_by_name’, 'name'],
[‘reviewed_by_email', 'email'],
[‘reviewed_by_id', 'user_id'],
[‘reviewed_at', 'event_at']
]
composed_of :submitted_attribution_event,
class_name: ’AttributionEvent',
allow_nil: true,
mapping: [
[‘submitted_by_name', 'name'],
[‘submitted_by_email’, 'email'],
[‘submitted_by_id', 'user_id'],
[‘submitted_at’, 'event_at']
]

34. class Sheet < ActiveRecord::Base
attribution_event :reviewed
attribution_event :submitted
attribution_event :discarded

36. module Models
module AttributionEvents
extend ActiveSupport::Concern
module ClassMethods
def attribution_event(type, allow_nil: true)
attribution_event = <<-ATTRIBUTION_EVENT
composed_of :#{type}_attribution_event,
class_name: 'AttributionEvent',
allow_nil: #{allow_nil},
mapping: [
['#{type}_by_name', 'name'],
['#{type}_by_email', 'email'],
['#{type}_by_id', 'user_id'],
['#{type}_at', 'event_at']
]
ATTRIBUTION_EVENT
class_eval(attribution_event)
end
end
end
end

37. module Models
module AttributionEvents
extend ActiveSupport::Concern
module ClassMethods
def attribution_event(type, allow_nil: true)
attribution_event = <<-ATTRIBUTION_EVENT
composed_of :#{type}_attribution_event,
class_name: 'AttributionEvent',
allow_nil: #{allow_nil},
mapping: [
['#{type}_by_name', 'name'],
['#{type}_by_email', 'email'],
['#{type}_by_id', 'user_id'],
['#{type}_at', 'event_at']
]
ATTRIBUTION_EVENT
class_eval(attribution_event)
end
end
end
end

38. module Models
module AttributionEvents
extend ActiveSupport::Concern
module ClassMethods
def attribution_event(type, allow_nil: true)
attribution_event = <<-ATTRIBUTION_EVENT
composed_of :#{type}_attribution_event,
class_name: 'AttributionEvent',
allow_nil: #{allow_nil},
mapping: [
['#{type}_by_name', 'name'],
['#{type}_by_email', 'email'],
['#{type}_by_id', 'user_id'],
['#{type}_at', 'event_at']
]
ATTRIBUTION_EVENT
class_eval(attribution_event)
end
end
end
end

39. module Models
module AttributionEvents
extend ActiveSupport::Concern
module ClassMethods
def attribution_event(type, allow_nil: true)
attribution_event = <<-ATTRIBUTION_EVENT
composed_of :#{type}_attribution_event,
class_name: 'AttributionEvent',
allow_nil: #{allow_nil},
mapping: [
['#{type}_by_name', 'name'],
['#{type}_by_email', 'email'],
['#{type}_by_id', 'user_id'],
['#{type}_at', 'event_at']
]
ATTRIBUTION_EVENT
class_eval(attribution_event)
end
end
end
end

40. module Models
module AttributionEvents
extend ActiveSupport::Concern
module ClassMethods
def attribution_event(type, allow_nil: true)
attribution_event = <<-ATTRIBUTION_EVENT
composed_of :#{type}_attribution_event,
class_name: 'AttributionEvent',
allow_nil: #{allow_nil},
mapping: [
['#{type}_by_name', 'name'],
['#{type}_by_email', 'email'],
['#{type}_by_id', 'user_id'],
['#{type}_at', 'event_at']
]
ATTRIBUTION_EVENT
class_eval(attribution_event)
end
end
end
end

41. include Models::AttributionEvents
attribution_event :reviewed
composed_of :reviewed_attribution_event,
class_name :'AttributionEvent',
allow_nil: true,
mapping: [
['reviewed_by_name', 'name'],
['reviewed_by_email', 'email'],
['reviewed_by_id', 'user_id'],
['reviewed_at', 'event_at']
]
Before
After

42. An attribution event
identifies a user and
has a timestamp
And there are different
types of attribution events

43. sheet.submitted_attribution_event =
AttributionEvent.build(inspector)
sheet.reviewed_attribution_event =
AttributionEvent.build(supervisor)
class Sheet < ActiveRecord::Base
include Models::AttributionEvents
attribution_event :reviewed
attribution_event :submitted
...
end

44. How do we { log, capture,
assign, save, or record }
an attribution event ?

45. sheet.log_attribution_event(
type: :reviewed, user: inspector, at: reviewed_at
)
sheet.capture_attribution_event(
type: :submitted, user: inspector, at: submitted_at
)
header.assign_attribution_event(
type: :reviewed, user: inspector, at: reviewed_at
)
inspection.save_attribution_event(
type: :submitted, user: inspector, at: reviewed_at
)
inspection.record_attribution_event(
type: :reviewed, user: inspector, at: reviewed_at
)

46. sheet.log_attribution_event(
type: :reviewed, user: inspector, at: reviewed_at
)
sheet.capture_attribution_event(
type: :submitted, user: inspector, at: submitted_at
)
header.assign_attribution_event(
type: :reviewed, user: inspector, at: reviewed_at
)
inspection.save_attribution_event(
type: :submitted, user: inspector, at: reviewed_at
)
inspection.record_attribution_event(
type: :reviewed, user: inspector, at: reviewed_at
)

47. sheet.log_attribution_event(
type: :reviewed, user: inspector, at: reviewed_at
)
sheet.capture_attribution_event(
type: :submitted, user: inspector, at: submitted_at
)
sheet.assign_attribution_event(
type: :reviewed, user: inspector, at: reviewed_at
)
inspection.save_attribution_event(
type: :submitted, user: inspector, at: reviewed_at
)
sheet.record_attribution_event(
type: :reviewed, user: inspector, at: reviewed_at
)

48. module Models
module AttributionEvents
extend ActiveSupport::Concern
included do
def capture_attribution_event(type:, user:,
at: Time.zone.now)
send("#{type}_attribution_event=",
AttributionEvent.build(user, at: at))
end
end
module ClassMethods
...
end
end
end

49. module Models
module AttributionEvents
extend ActiveSupport::Concern
included do
def capture_attribution_event(type:, user:,
at: Time.zone.now)
send("#{type}_attribution_event=",
AttributionEvent.build(user, at: at))
end
end
module ClassMethods
...
end
end
end

50. module Models
module AttributionEvents
extend ActiveSupport::Concern
included do
def capture_attribution_event(type:, user:,
at: Time.zone.now)
send("#{type}_attribution_event=",
AttributionEvent.build(user, at: at))
end
end
module ClassMethods
...
end
end
end

51. sheet.capture_attribution_event(
type: :submitted, user: inspector
)
Before
After
sheet.submitted_by_name = inspector.name
sheet.submitted_by_email = inspector.email
sheet.submitted_by_id = inspector.id
sheet.submitted_at = Time.zone.now

52. Example from
QCloud
composed_of Concern

53. An attribution event
identifies a user and
has a timestamp
And we capture different
types of attribution events

54. class Sheet < ActiveRecord::Base
include Models::AttributionEvents
attribution_event :reviewed
attribution_event :submitted
sheet.capture_attribution_event(
type: :submitted, user: inspector
)
An attribution event
identifies a user and
has a timestamp
And we capture different
types of attribution events

55. class Sheet < ActiveRecord::Base
include Models::AttributionEvents
attribution_event :reviewed
attribution_event :submitted
sheet.capture_attribution_event(
type: :submitted, user: inspector
)

56. Naming
is deeply
connected to
Designing

58. Ubiquitous
Language
The language used by everyone on the team
to describe the domain model when speaking,
writing user stories, and in the source code.

59. • Passes the tests
• Reveals intention
Simple
Design
• No duplication
• Fewest elements

60. • Passes the tests
• Reveals intention
Simple
Design
• No duplication
• Fewest elements

61. • Passes the tests
• Reveals intention
Simple
Design
• No duplication
• Fewest elements

62. • Passes the tests
• Improves names
Simple
Design
• No duplication
• Fewest elements

63. • Improves names
Simple
Design
• Removes duplication

64. • Improves names
Simple
Design
• Removes duplication

65. The Simple Design Dynamo™

66. Example from
QCloud

68. class Sheet < ActiveRecord::Base
composed_of :reviewed_attribution_event,
class_name: 'AttributionEvent',
allow_nil: true,
mapping: [
['reviewed_by_name', 'name'],
['reviewed_by_email', 'email'],
['reviewed_by_id', 'user_id'],
['reviewed_at', 'event_at']
]
composed_of :submitted_attribution_event,
class_name: ’AttributionEvent',
allow_nil: true,
mapping: [
['submitted_by_name', 'name'],
['submitted_by_email', 'email'],
['submitted_by_id', 'user_id'],
['submitted_at', 'event_at']
]

69. #
# Represents the information required to attribute
# an event to a user.
#
class AttributionEvent
attr_reader :name, :email, :user_id, :event_at
def initialize(name, email, user_id, at)
@name = name
@email = email
@user_id = user_id
@event_at = at
end
end
sheet.submitted_attribution_event =
AttributionEvent.new(
inspector.name, inspector.email,
inspector.id, Time.zone.now
)

70. #
# Represents the information required to attribute
# an event to a user.
#
class AttributionEvent
attr_reader :name, :email, :user_id, :event_at
def self.build(user, at: Time.zone.now)
new(user.name, user.email, user.id, at)
end
def initialize(name, email, user_id, at)
@name = name
@email = email
@user_id = user_id
@event_at = at
end
end
An attribution event
identifies a user and
has a timestamp

71. class Sheet < ActiveRecord::Base
composed_of :reviewed_attribution_event,
class_name: ’AttributionEvent',
allow_nil: true,
mapping: [
[‘reviewed_by_name’, 'name'],
[‘reviewed_by_email', 'email'],
[‘reviewed_by_id', 'user_id'],
[‘reviewed_at', 'event_at']
]
composed_of :submitted_attribution_event,
class_name: ’AttributionEvent',
allow_nil: true,
mapping: [
[‘submitted_by_name', 'name'],
[‘submitted_by_email’, 'email'],
[‘submitted_by_id', 'user_id'],
[‘submitted_at’, 'event_at']
]

72. module Models
module AttributionEvents
extend ActiveSupport::Concern
module ClassMethods
def attribution_event(type, allow_nil: true)
attribution_event = <<-ATTRIBUTION_EVENT
composed_of :#{type}_attribution_event,
class_name: 'AttributionEvent',
allow_nil: #{allow_nil},
mapping: [
['#{type}_by_name', 'name'],
['#{type}_by_email', 'email'],
['#{type}_by_id', 'user_id'],
['#{type}_at', 'event_at']
]
ATTRIBUTION_EVENT
class_eval(attribution_event)
end
end
end
end

74. class Sheet < ActiveRecord::Base
include Models::AttributionEvents
attribution_event :reviewed
attribution_event :submitted
sheet.capture_attribution_event(
type: :submitted, user: inspector
)
sheet.capture_attribution_event(
type: :reviewed, user: supervisor
)

75. The Simple Design Dynamo™

76. Don’t Settle for
Poor Names

77. Don’t Settle for
Poor Names
Pretty Please

79. The Simple Design Dynamo™

81. Resources

82. http://blog.jbrains.ca/permalink/the-four-elements-of-simple-design
http://blog.thecodewhisperer.com/permalink/putting-an-age-old-battle-to-rest
One of the best thinkers around on effective
software development: J. B. Rainsberger.