The document discusses attribution events in software design. An attribution event identifies a user and has a timestamp. Sheets can have different types of attribution events, like submitted and reviewed events. A module defines methods to capture attribution events, which assigns an AttributionEvent object to the appropriate attribute on the model. This provides a cleaner way to track who performed different actions on a sheet and when.

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

2. 1974

7. Naming
is deeply
connected to
Designing

8. Designing
is deeply
connected to
Naming

9. Example from
QCloud

10. QCloud has forms,
sheets, and inspections

11. QCloud has forms,
sheets, and inspections

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

21. class Sheet < ActiveRecord::Base

22. 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']
]

23. 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']
]

24. 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']
]

25. 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']
]

26. #
# 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']
]

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

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

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

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

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

32. #
# 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

33. 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

34. 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

35. 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

36. #
# 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

37. #
# 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

38. 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

39. 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

40. 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
!

41. 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

42. 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
!

43. 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

44. #
# 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

45. 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']
]

46. 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']
]

47. class Sheet < ActiveRecord::Base
attribution_event :reviewed
attribution_event :submitted

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

51. 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

52. 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

53. 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

54. 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

55. 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

56. 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

57. 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

58. 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

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

60. 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

61. 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

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

63. 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
)

64. 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
)

65. 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
)

66. 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

67. 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

68. 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

69. 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

70. 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

71. Example from
QCloud
composed_of Concern

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

73. 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

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

75. Naming
is deeply
connected to
Designing

76. Designing
is deeply
connected to
Naming

78. 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.

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

80. Simple
Design
• Removes duplication
• Improves names

81. The Simple Design Dynamo™

82. Example from
QCloud

84. 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']
]

85. #
# 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
)

86. #
# 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

87. 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']
]

88. 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

90. 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
)

91. The Simple Design Dynamo™

92. Don’t Settle for
Poor Names

93. Don’t Settle for
Poor Names
Pretty Please