Inconsistencies

[thekid]

The library feels a bit inconsistent at the moment:

Usage

Some traits are parametrized, others not:

use lang\partial\Identity;               // Same here
use lang\partial\Comparators;            // :-)

class Name extends \lang\Object {
  use Identity;                          // Different here!
  use Name\including\Comparators;        // :-(
}

This is because Identity is a "plain" trait, while Comparators is a transformation. Maybe we can find a way around this so the user need not distinguish (while at the same time not being a major performance degradation?)

Naming

The names are inconsistent:

• WithCreation goes along the line "with [general concept]"
• Constructor explicitly uses the well-known technical term for what's generated
• ValueObject only generates setters, generally people would expect set[X] and get[X].
• Sortable uses an "interface"-style

[thekid]

:bulb: Usage: is

Use use Name\including\Identity; or use Name\including\ListOf; is a bit problematic, because it doesn't include anything but makes it something; the words is or as would be better. We could simply support both syntaxes, leaving it up to the user when to use what, and decide during class loading if we're handling a transformation or a regular trait.

use lang\partial\Identity;
use lang\partial\Comparators;

class Name extends \lang\Object {
  use Name\is\Identity;
  use Name\with\Comparators;
}

[thekid]

:bulb: Naming

Strategy: Use technical / design pattern names. In most cases, we're already there, in some, we need to rename. Plural form denotes multiple members are generated, singular only creates a single field or method.

The ValueObject transformation includes read-only accessors, equals() and toString() today. This comes close to a value object minus the constructor as described in xp-framework/rfc#294, which I personally like, but people might misunderstand. Along with the aforementioned strategy, it should be split as follows:

• lang.partial.Accessors - only the accessor methods
• lang.partial.Equals - only equals(var $cmp)
• lang.partial.ToString - only toString()

This way, Equals can the be complemented by HashCode and ToString to form a lang.Generic style value object. To build lang.Value instances we can compose CompareTo, HashCode and ToString.

This also leaves room for Getters (a special form of accessors starting with get) and Setters (a special form of mutators starting with set). In the future, we could create Mutable as a combination of those, as well as Immutable as a combination of accessors and the constructor.

Resulting changes

Use case	Old name	New name
is	lang.partial.Identity	lang.partial.ReferenceTo
is	lang.partial.ListIndexedBy	(unchanged)
is	lang.partial.ListOf	(unchanged)
is	lang.partial.ValueObject	(split into composeable usecases, see below)
with	(ValueObject split)	lang.partial.Accessors
with	(ValueObject split)	lang.partial.Equals
with	(ValueObject split)	lang.partial.ToString
with	_(new)_	lang.partial.HashCode
with	lang.partial.Comparators	(unchanged)
with	lang.partial.Constructor	(unchanged)
with	lang.partial.Sortable	lang.partial.CompareTo
with	lang.partial.WithCreation	lang.partial.Builder