Naming conventions

[Jason Voegele]

Is there an established set of naming conventions contexts and roles within DCI? Specifically, I'm interested in advice on the following:

* Should context classes be named as nouns, verbs, or other?

* What form of speech should roles be named with?

* Is it common to use suffixes on context and/or role names to identify them as such (i.e. TransferMoneyContext, SourceAccountRole, etc.)

Any other conventions that I should be aware of or think about? (If this information is already documented somewhere, feel free to just post the link.)

Thanks.

-- 

Jason Voegele

A boss with no humor is like a job that's no fun.

[Jim Gay]

The answers may depend upon your project needs. You should think about
the language you use to describe the use case.

I don't include "Context" or "Role" in my names; it's redundant.
I often find myself choosing a gerund for a context name (e.g.
BookPurchasing), but not always.
A role is what your object is. You are a waiter, a chef, a customer,
etc. Nouns fit that well.

> --
> You received this message because you are subscribed to the Google Groups
> "object-composition" group.
> To post to this group, send email to object-co...@googlegroups.com.
> To unsubscribe from this group, send email to
> object-composit...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/object-composition?hl=en.



--
Write intention revealing code #=> http://www.clean-ruby.com

Jim Gay
Saturn Flyer LLC
571-403-0338

[Jason Voegele]

On May 8, 2012, at 4:10 PM, Jim Gay wrote:

The answers may depend upon your project needs. You should think about
the language you use to describe the use case.

I don't include "Context" or "Role" in my names; it's redundant.
I often find myself choosing a gerund for a context name (e.g.
BookPurchasing), but not always.
A role is what your object is. You are a waiter, a chef, a customer,
etc. Nouns fit that well.

Thanks Jim, that is helpful. I especially like the use of gerunds for context names, which hadn't at all occurred to me. Also, naming roles as nouns is obvious in hindsight, given your explanation that they are logically part of the objects that they are attached to.

Thanks.

-- 

Jason Voegele

Many people feel that they deserve some kind of recognition for all the

bad things they haven't done.

[rune funch]

Den 08/05/2012 kl. 22.43 skrev Jason Voegele <jason....@gmail.com>:

> logically part of the objects that they are attached

roles aren't bound to objects. Objects play a role. Neither object nor
role is aware of this

-Rune

[rune funch]

I tend to have most of my objects being contexts and the naming convention follows what each context models. If it's a use case I name it after the UC if it's a physical object eg. account I name it after the object. I like prefixing/postfixing with role/ctx as much as I like Hungarian notation (which not a lot). It's redundant and might even be confusing. I don't think the confusion is that much a problem if you have no nested context but when you do nest I find the distinction between contexts and other objects that plays roles to be rather arbitrary

-Rune

[Justin Ko]

On Tuesday, May 8, 2012 1:51:18 PM UTC-6, Jason Voegele wrote:

Is there an established set of naming conventions contexts and roles within DCI? Specifically, I'm interested in advice on the following:

* Should context classes be named as nouns, verbs, or other?

Use cases are made up of actions. Actions are made up of verbs. I've yet to to create a context that is not a verb.

 

* What form of speech should roles be named with?

I've yet to create a role that is not a noun.

 

* Is it common to use suffixes on context and/or role names to identify them as such (i.e. TransferMoneyContext, SourceAccountRole, etc.)

I prefer to know when a class is a context, and not a service class, for example. Name spacing (Contexts::TransferMoney) or suffix helps with this, and also avoids name collisions.

In Ruby, I usually nest the roles within the contexts, so no need to do any of the above.

[Jim Gay]

On Wed, May 9, 2012 at 6:14 PM, Justin Ko <jko...@gmail.com> wrote:
> I prefer to know when a class is a context, and not a service class, for
> example. Name spacing (Contexts::TransferMoney) or suffix helps with this,
> and also avoids name collisions.
>

I'm curious about this. Why do you need to know if you have a context
or a service class?
When, in your own code, would you have name collisions on something
like TransferMoney?

[Justin Ko]

On May 9, 2012, at 9:32 PM, Jim Gay wrote:

> On Wed, May 9, 2012 at 6:14 PM, Justin Ko <jko...@gmail.com> wrote:
>> I prefer to know when a class is a context, and not a service class, for
>> example. Name spacing (Contexts::TransferMoney) or suffix helps with this,
>> and also avoids name collisions.
>>
>
> I'm curious about this. Why do you need to know if you have a context
> or a service class?

When you're dealing with an object, you want to know what its responsibilities are. Our mental model for a context is different than for a service (at least to me). We have certain expectations for a context: dumb, dumber, triggers, state, use case, etc. Therefore, when viewing the context object "in action", I can "fail" these expectations in my head to produce better code or a better design. For example, if I see a context object call a method that serializes itself to JSON (with some added nodes for logic), I can throw a red flag. If this context's class is named "SerializeObject", it could be a service class, utility class, etc. and serializing itself is perfectly valid.

Of course, if you forget or don't know what the class is, you can always use your editor to quickly find out, but that adds mental overhead.

Imagine the challenges created if half of the women in the world suddenly had boy names...

> When, in your own code, would you have name collisions on something
> like TransferMoney?

Name collisions are easy.

For example, in Rails, if you create a database migration named "CreateUsers", you'll get a top-level class named CreateUsers. Hmmm, that name sounds like a service class to me. I suffix all of my migration classes with "Migration".

Also, the odds of a name collision increase ten-fold for newcomers to a codebase. Avoid surprises by being a tiny bit more verbose.

>
> --
> Write intention revealing code #=> http://www.clean-ruby.com
>
> Jim Gay
> Saturn Flyer LLC
> 571-403-0338
>

[Jim Gay]

On Thu, May 10, 2012 at 12:45 AM, Justin Ko <jko...@gmail.com> wrote:
>
> On May 9, 2012, at 9:32 PM, Jim Gay wrote:
>
>> On Wed, May 9, 2012 at 6:14 PM, Justin Ko <jko...@gmail.com> wrote:
>>> I prefer to know when a class is a context, and not a service class, for
>>> example. Name spacing (Contexts::TransferMoney) or suffix helps with this,
>>> and also avoids name collisions.
>>>
>>
>> I'm curious about this. Why do you need to know if you have a context
>> or a service class?
>
> When you're dealing with an object, you want to know what its responsibilities are. Our mental model for a context is different than for a service (at least to me). We have certain expectations for a context: dumb, dumber, triggers, state, use case, etc. Therefore, when viewing the context object "in action", I can "fail" these expectations in my head to produce better code or a better design. For example, if I see a context object call a method that serializes itself to JSON (with some added nodes for logic), I can throw a red flag. If this context's class is named "SerializeObject", it could be a service class, utility class, etc. and serializing itself is perfectly valid.
>
> Of course, if you forget or don't know what the class is, you can always use your editor to quickly find out, but that adds mental overhead.

I'm not sure I fully understand your argument.
Have you actually had this problem or are you anticipating it?

What we can learn from DCI is that *any* object is or can be a
context. If you create a program where an Account is a simple object,
but later realize that it's much more complex than that and its
internal structure is that of collaborating objects, would you go and
change all references from Account to Context::Account? What benefit
would that give you? The behavior is still the same, but the
composition is different. Outside that object, your program only cares
about the behavior.

>
> Imagine the challenges created if half of the women in the world suddenly had boy names...

I don't think that's an apt comparison, but I understand your point.

>
>> When, in your own code, would you have name collisions on something
>> like TransferMoney?
>
> Name collisions are easy.
>
> For example, in Rails, if you create a database migration named "CreateUsers", you'll get a top-level class named CreateUsers.  Hmmm, that name sounds like a service class to me. I suffix all of my migration classes with "Migration".
>

That seems like a fine solution. You would be better served to merely
rename your migration. You *never* type the name of a migration in
your program. Its name is incidental, so you should preserve the name
you want (CreateUsers) for your own needs.

> Also, the odds of a name collision increase ten-fold for newcomers to a codebase. Avoid surprises by being a tiny bit more verbose.

That sounds like hyperbole.
And I'd err on the side of naming a service class explicitly. I
personally don't often use service classes, so they are more rare in
my programs. If I use DCI, typing Context:: all over would annoy me
especially if I chose a convention like that and refactored existing
objects and classes to go from non-context to context.

[Justin Ko]

On Thursday, May 10, 2012 7:45:03 AM UTC-6, Jim Gay wrote:

On Thu, May 10, 2012 at 12:45 AM, Justin Ko wrote:
>
> On May 9, 2012, at 9:32 PM, Jim Gay wrote:
>
>> On Wed, May 9, 2012 at 6:14 PM, Justin Ko wrote:
>>> I prefer to know when a class is a context, and not a service class, for
>>> example. Name spacing (Contexts::TransferMoney) or suffix helps with this,
>>> and also avoids name collisions.
>>>
>>
>> I'm curious about this. Why do you need to know if you have a context
>> or a service class?
>
> When you're dealing with an object, you want to know what its responsibilities are. Our mental model for a context is different than for a service (at least to me). We have certain expectations for a context: dumb, dumber, triggers, state, use case, etc. Therefore, when viewing the context object "in action", I can "fail" these expectations in my head to produce better code or a better design. For example, if I see a context object call a method that serializes itself to JSON (with some added nodes for logic), I can throw a red flag. If this context's class is named "SerializeObject", it could be a service class, utility class, etc. and serializing itself is perfectly valid.
>
> Of course, if you forget or don't know what the class is, you can always use your editor to quickly find out, but that adds mental overhead.

I'm not sure I fully understand your argument.
Have you actually had this problem or are you anticipating it? 

Maybe because I'm new to DCI, suffixing "Context" helps with implementation.... 

 

What we can learn from DCI is that *any* object is or can be a
context. If you create a program where an Account is a simple object,
but later realize that it's much more complex than that and its
internal structure is that of collaborating objects, would you go and
change all references from Account to Context::Account? What benefit
would that give you? The behavior is still the same, but the
composition is different. Outside that object, your program only cares
about the behavior.

This is simply not true.

Contexts must have certain characteristics for us to call it a context. This goes with any object in the universe...

Let's say I have an object like this:

object = Account.new

object.expunge

object.each_audit_log_item {|item| item.send_to_accounting }

This object has a method named #each_audit_log_item. You cannot simply "turn this into a context" because a context (the director) is not supposed to act; he is supposed to direct.

Therefore, you must change its behavior before you can turn it into a context. And when you suffix the object class with "Context", you *lock in* its characteristics. I understand that the computer doesn't care - this is all for the human.

If you are talking about an object that already meets the characteristics of a context, then yes you are correct. But let me say it again: naming can help lock this in.

 

>
> Imagine the challenges created if half of the women in the world suddenly had boy names...

I don't think that's an apt comparison, but I understand your point.

>
>> When, in your own code, would you have name collisions on something
>> like TransferMoney?
>
> Name collisions are easy.
>
> For example, in Rails, if you create a database migration named "CreateUsers", you'll get a top-level class named CreateUsers.  Hmmm, that name sounds like a service class to me. I suffix all of my migration classes with "Migration".
>

That seems like a fine solution. You would be better served to merely
rename your migration. You *never* type the name of a migration in
your program. Its name is incidental, so you should preserve the name
you want (CreateUsers) for your own needs.

In Ruby, you cannot "preserve" classes. If you've found out that there is a name collision, most likely you found out the hard way.

 

> Also, the odds of a name collision increase ten-fold for newcomers to a codebase. Avoid surprises by being a tiny bit more verbose.

That sounds like hyperbole.
And I'd err on the side of naming a service class explicitly. I
personally don't often use service classes, so they are more rare in
my programs. If I use DCI, typing Context:: all over would annoy me
especially if I chose a convention like that and refactored existing
objects and classes to go from non-context to context.

In every MVC project I've worked on (Rails and Ember.js), the domain classes get priority with naming. In Rails, you have this (these are classes):

User # model

UsersController # controller

UserHelper # helper module for the view

UserPresenter # presenter for the view

Take away the suffixes, can you see the collisions? Why not extend this protection-by-suffix to DCI?

[rune funch]

Den 11/05/2012 kl. 06.50 skrev Justin Ko <jko...@gmail.com>:

> This object has a method named #each_audit_log_item. You cannot simply "turn this into a context" because a context (the director) is not supposed to act; he is supposed to direct.

The context is _not_ directing. Jim is correct in saying that every
object can be (implemented internally) as a context

[Justin Ko]

This makes sense for internal implementation. But do you think that the object's interface, which denotes behaviour, conflicts with the characteristics of a context?

[rune funch]

Den 11/05/2012 kl. 07.20 skrev Justin Ko <jko...@gmail.com>:

>
> On May 10, 2012, at 10:57 PM, rune funch wrote:
>
>> Den 11/05/2012 kl. 06.50 skrev Justin Ko <jko...@gmail.com>:
>>
>>> This object has a method named #each_audit_log_item. You cannot simply "turn this into a context" because a context (the director) is not supposed to act; he is supposed to direct.
>>
>> The context is _not_ directing. Jim is correct in saying that every
>> object can be (implemented internally) as a context

Any object regardless of it's behaviour/interface can be implemented
as a context. Whether or not that it is will not be visible from the
outside.

-Rune

[Justin Ko]

On May 10, 2012, at 11:23 PM, rune funch wrote:

> Den 11/05/2012 kl. 07.20 skrev Justin Ko <jko...@gmail.com>:
>
>>
>> On May 10, 2012, at 10:57 PM, rune funch wrote:
>>
>>> Den 11/05/2012 kl. 06.50 skrev Justin Ko <jko...@gmail.com>:
>>>
>>>> This object has a method named #each_audit_log_item. You cannot simply "turn this into a context" because a context (the director) is not supposed to act; he is supposed to direct.
>>>
>>> The context is _not_ directing. Jim is correct in saying that every
>>> object can be (implemented internally) as a context
>
> Any object regardless of it's behaviour/interface can be implemented
> as a context. Whether or not that it is will not be visible from the
> outside.

Technically, this is true. On a practical level, it is not.

If you have an object that is using a method named #add_role externally, that is a violation to a context. In DCI, because the word "role" has meaning, this affects/influences the interface of objects.

[rune funch]

Den 11/05/2012 kl. 08.00 skrev Justin Ko <jko...@gmail.com>:

> If you have an object that is using a method named #add_role externally, that is a violation to a context. In DCI, because the word "role" has meaning, this affects/influences the interface of objects.

The method name should reflect the domain being modelled and so if the
domain has then need for add_role this has nothing to do with DCI.
I'm a compiler writer and as such have a class called class and a
plethora of methods called something similar to add_class. The
paradigm I've used is class oriented so the term class bears special
meaning in that paradigm but that does not influence the domain I'm
modelling and it so happens that the modelled domain has an entity
known as a class.

To make matters even more confusing I might have an expression
returning a statement and a statement representing an expression. We
always have to deal with at least three domains when we code

The problem domain (what are the problems we are helping the users solve)
The solution domain (How do we solve the problems)
The environment (Which constructs are we lent by our chosen platform/paradigm)

We try our best to align the terminology between problem and solution
domain but at times this terminology conflicts with that of the used
paradigm. Eg. if you model a university you might have a class called
class or if it's a game played out in court you might have a _method_
called object that returns an object of type objection.

It doesn't invalidate the domain model nor the paradigm. It might
potentially create confusion which we should try to avoid but changing
class to asseblyOfStudentsBeingTaught is not going to reduce the
confusion either after all it really is a class we're modelling and we
are really using a class to model it with. Some words are used in
different ways in different contexts and there's nothing we do that's
going to change it and trying to will often lead to a confusion or
other communication challenges such as the developers calling a
concept one thing and the business calling it some thing else or even
worse the two groups using the same term but with two slightly
different meanings which is almost impossible to spot and correct

-Rune

[Justin Ko]

> --
> You received this message because you are subscribed to the Google Groups "object-composition" group.
> To post to this group, send email to object-co...@googlegroups.com.
> To unsubscribe from this group, send email to object-composit...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/object-composition?hl=en.
>

You are 100% correct. Thanks for the thorough explanation.

An "authorization" context could easily have trigger methods involving the term "role".

[Trygve Reenskaug]

Hi Rune,
Any object can clearly not be implemented as a context because objects and contexts have different lifetimes. The short story is that while a regular object lives on the heap and has an indefinite lifetime, the DCI Context lives on the stack and only exists for the duration of a system operation. The two ideas are not interchangeable. For pure behavior: yes. For handling state: no.

DCI goes back to the roots of the Simula objects. Simula has evolved into class oriented programming. DCI has added the Context, a new stack discipline that gives better control with object interaction. The Simula roots were well described by Andrew P. Black in his talk "Object-oriented programming: challenges for the next fifty years" at the University of Oslo on 25 Aug. 2011. The talk is well worth pursuing. Google the title to find it. I'll use a few quotes as a background:

“In ALGOL 60, the rules of the language have been carefully
designed to ensure that the lifetimes of block instances are
nested, in the sense that those instances that are latest
activated are the first to go out of existence. It is this feature
that permits an ALGOL 60 implementation to take advantage
of a stack as a method of dynamic storage allocation and
relinquishment. But it has the disadvantage that a program
which creates a new block instance can never interact with it
as an object which exists and has attributes, since it has
disappeared by the time the calling program regains control.
Thus the calling program can observe only the results of the
actions of the procedures it calls. Consequently, the
operational aspects of a block are overemphasised; and
algorithms (for example, matrix multiplication) are the only
concepts that can be modelled.” [Dahl1972]"
---
"Two simple changes:
“In SIMULA 67, a block instance is permitted
to outlive its calling statement, and to remain
in existence for as long as the program needs
to refer to it.” [Dahl1972]
A way of referring to “it”: object references as
data."
---
Dahl was inspired by
visualizing the runtime
representation of an Algol 60
program:
Objects were already in
existence inside every
executing Algol program —
they just needed to be freed
from the “stack discipline”

DCI is different from all this:

• Data, what the system IS, regular objects à la Simula, freed from the "stack discipline".
• Context: A special block instance that creates a namespace for blocks above it on the stack. Contexts are nested, in the sense that those instances that are latest activated are the first to go out of existence. 
• Interaction: A procedure-like execution of Role Methods within the namespace defined by the top context..

Any object can clearly not be implemented as a context because they have different lifetimes.

Cheers
--Trygve

On 2012.05.11 07:23, rune funch wrote:

Any object regardless of it's behaviour/interface can be implemented
as a context. Whether or not that it is will not be visible from the
outside.

-Rune
  

--

Trygve Reenskaug       mailto: try...@ifi.uio.no

Morgedalsvn. 5A         http://folk.uio.no/trygver/

N-0378 Oslo               Tel: (+47) 22 49 57 27

Norway