liveBook · Manning

Code readability

As explained in The Art of Code

Readability is the ease with which source code can be understood by its readers.

Readability is the ease with which readers can understand source code. Readable code makes its intent apparent without requiring readers to reconstruct every step. It can also tell an engaging, memorable story about what the program does. section 1.1.1 section 5.1

Conciseness helps only when it preserves clarity. A short construct can be cryptic; a longer one can make each operation explicit. Choose the level of detail that suits the team’s experience and the surrounding code. section 5.1 section 5.2

Make the main actions visible

A promotional-message function uses chained Kotlin scope functions to shorten a title, normalize a digital download link, log values, and format messages for different book types. The compact chain asks the reader to unpack several operations before seeing the overall flow. section 5.2

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…"
        }
    }

The chained version combines title shortening, link processing, and message formatting in one expression. 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…")
    }

The revised function names the formatting actions and makes the book-type branches visible; the details move into extracted methods. section 5.2

Well-named methods let readers follow higher-level actions instead of mentally grouping low-level mechanics. In a user-registration function, named validation and save steps make the flow clearer—and make the absence of first-name validation easier to spot. Names should convey their purpose without forcing a reader to inspect their implementations. section 2.3.3

Use readability as a constraint when comparing solutions. A method reference may be concise, a loop more explicit, and a lambda a useful middle ground. Prefer the version that communicates the logic to its likely readers, rather than the shortest or most advanced idiom by default. section 5.2 section 10.2.1

How The Art of Code covers it

How deep it goes
Explains readability through method extraction and idiom tradeoffs, while leaving general readability lessons aside.
Examples
Compares Kotlin promotional-message implementations and Java iteration idioms, and examines extracted validation and save methods.
What you can do after
Evaluate code for clarity and choose idioms or extracted methods suited to readers and surrounding code.
How it connects
Connects readability with expressiveness, simplicity, conciseness, and cognitive complexity.

Also explained in

Compare how 13 books explain code readability →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of The Art of Code. The section links point to the parts of the book it draws on.