Conventions
Its a tough balance to make method names meaningful, short and familiar. Here are some of the established conventions in the AndHow Project. These conventions represent what has happened up to this point and why. Community direction in the future could easily change this.
These Property classes are the main interaction point for most users, so the names used are important. Existing Property names, such as StrProp, IntProp, BigDecProp, and LocalDateTimeProp follow these conventions:
The names all end with Prop rather than Property to keep the names short
For property types that are based on a boxed primative, the type is shortened to three characters, such as BolProp, DblProp, IntProp and LngProp. The idea here is that these types are so common and familiar that anyone will recognize what the type is, even in this short form.
BigDecProp and LocalDateTimeProp show the limits of abbreviation. 'BigDec' is still pretty recognizable in its shortened form, while 'LocalDateTime' can't really be abbreviated without becoming ambiguous.
FlagProp is special purpose - Its a boolean type with special usage and behaviours. As a precident, it would be purpose wins over datatype.
If the Property classes are the most visible classes of AndHow, the builder methods used to assemble the instances are the most visible methods. Most of those methods are validation / requirements related. Prior to version 0.4.2, all of those methods began with must or mustBe. Those names were clear, but too long. As a result of a discussion resulting in several tasks, those method names were shorted.
The intent was to base the validation methods on existing, well-known validation or assertion methods. For String related validation, this was easy since the String class has several assertion style methods to copy from. Things were less clear cut for numeric or date related validation. Here are notable precidents:
StrProp.StrPropBuilder.oneOf() and startsWithIgnoringCase() is based on Hamcrest Matchers
Numeric validation methods are all based on Hamcrest Matchers as well
PropertyBuilderBase.notNull(), which is used by all builders, is based on JUnit assertions (isNotNull in JUnit)
LocalDateTimeBuilder validation is based on a Hamcrest extension for validating dates and times
The general guide in preference order might be:
Use true/false assertion method names from the type class if possible, e.g. String.startsWith()
Use Java utility comparison / assertion / validation method names were possible (no current examples of this)
Use JUnit assertion method names, though these often need to have 'assert' or 'is' prefixes removed
Use Hamcrest or a Hamcrest extension for the type as a reference
Last updated