Code readability is the ease with which a reader can understand intent and follow the logic. More than legibility, it can make code enjoyable and memorable when the implementation reads like a story rather than a sequence to reconstruct. section 1.1.1 section 5.3
Brevity is not readability. Concise code is expressive only when it remains simple enough to understand quickly; a shorter construct becomes cryptic when it raises the mental effort needed to recover control flow, cases, and intent. section 5.1 section 5.2
Make the code’s story easier to follow by:
- Name and extract high-level actions so low-level mechanics do not obscure the plot. section 2.3.3
- Choose the clearest idiom for the readers and surrounding code, not automatically the shortest one. section 5.2
- Use advanced language features when they improve clarity, safety, or closeness to the problem; avoid cleverness for its own sake. section 5.2
- Compare alternative implementations under constraints, then deliberately produce the most self-explanatory version. section 10.2.1
Turn mechanics into named actions
A user-creation method becomes easier to scan when validation and persistence appear as a few named steps. The reader can follow the overall action and notice whether a responsibility, such as first-name validation, is missing. section 2.3.3
fun getPromotionalMessage(book: Book): String =
book.run {
val shortTitle = title.let {
if (it.length > 150) it.take(150) + "..." else it
}
when (this) {
is DigitalBook -> downloadLink
.also { println("Raw download link: $it") }
.let {
if (it.startsWith("http://")) {
it.replaceFirst("http://", "https://")
} else {
it
}
}
.also { println("Normalized download link: $it") }
.let { link -> "$shortTitle: $link" }
is PocketBook ->
"$shortTitle: Same book, smaller format!"
is HardcoverBook ->
"$shortTitle: Old-fashioned book…"
}
}
Dense Kotlin scope-function chains can hide a straightforward sequence: shorten a title, normalize a link, log it, and format a message. Compare this version with the extracted-method alternative to judge whether concision has become cryptic. section 5.2
fun getPromotionalMessage(book: Book): String =
when (book) {
is DigitalBook -> formatDigitalBookMessage(book.title,
book.downloadLink)
is PocketBook -> formatPromotionalMessage(book.title,
"Same book, smaller format!")
is HardcoverBook -> formatPromotionalMessage(book.title,
"Old-fashioned book…")
}
This alternative makes the main decision explicit and delegates formatting details to named methods, producing a clearer narrative at the call site. section 5.2
