strings.avoid.md

Overview

1. Why Strings are problematic?
2. How can we do better?

Strings make bad properties

1. String is ambiguous, because it can represent anything
2. String type provides zero information about structure
3. String is not self documenting. Future readers have no way of finding all possible values
4. String is not self verifying. The compiler & runtime don't have a way to enforce correct values
5. String properties discard all the benefits of type safety
6. String properties prevent JVM optimization
7. String properties prevent refactoring
8. String properties hinder code maintenance
9. String properties hinder code comprehension

Making a String useful

1. Always prefer a better type (examples below)
2. Include Javadoc with structure assumptions
   1. Document acceptable characters, including case (eg. use regex)
   2. Document min & max length (eg. use regex)
   3. Document nullability
   4. Include an example
3. Enforce structure assumptions using preconditions (eg. use a Pattern)
4. Use a clear variable name
5. Add a link to any authoritative documentation that would help future readers/maintainers

Examples of Useful Strings

/**
 * Full US Postal zip code:
 * [0-9]{5}-[0-9]{4}
 *
 * eg. "08081-1234"
 */
final String fullZipCode;

/**
 * Unique ID within ABC company
 * [A-Z0-9]{6}
 *
 * eg. "1WC45Z"
 */
final String employeeId;

/**
 * As defined by RFC2822
 *
 * eg. "foo@bar.com"
 *
 * <p>See https://datatracker.ietf.org/doc/html/rfc2822
 */
final String emailAddress;

/**
 * Family/Last name
 * [A-Za-z- ]{3,32}
 *
 * eg. "Carmon"
 */
@Nullable
final String lastName;

/**
 * RGB hex value
 * [0-9a-f]{6} or empty-string (never null)
 *
 * eg. "00aaff"
 *
 * <p>See https://en.wikipedia.org/wiki/Web_colors
 */
final String hexColorCode;

/**
 * Minimum structure: [0-9-+ ]{12,16}
 * Parser imposes more strict structure
 *
 * eg. "+1 201-404-5555"
 */
final String phoneNumber;

Replace String with ...

1. boolean for Strings like "Y" & "N" or "T" & "F"
2. Duration or Period for Strings that look like time periods/durations
3. Google LibPhoneNumber for Strings containing phone numbers (or just a really clear Javadoc & regex Pattern)
4. Instant for Strings that look like dates (no timezone info)
5. LocalTime for Strings that look like times (eg. "When does the meeting start?")
6. long or BigDecimal or double for Strings that contain only numbers
7. Map for Strings that look like key-value pairs (eg. "a=5,b=9,...")
8. MonthDay for Strings with just month and day
9. OffsetDateTime for Strings with date-time & timezone
10. Path for Strings that looks like files/paths/directories
11. URI for Strings that look like urls or resource addresses
12. UUID for Strings containing a uuid
13. WeekFields or int for Strings containing a week
14. YearMonth for Strings representing year and month
15. ZoneId or ZoneOffset for Strings containing timezone info
16. Enum for bounded set of values
17. List or Set for repeated values (eg. comma separated)
18. char for Strings that only contain 1 character
19. int for Strings containing a year