Tales from the jar side: Humor in tech writing, Making Gradle warnings go away, Modern Major General parodies, and more

A weasel walks into a bar and the bartender says “wow, I’ve never seen a weasel here before. What can I get you?” “Pop”, goes the weasel. (rimshot)

Welcome, fellow jarheads, to Tales from the jar side, the Kousen IT newsletter, for the week of June 2 - 9, 2024. This week I taught my Latest Features in Java course as an NFJS Virtual Workshop.

• Regular readers of, listeners to, and video viewers of this newsletter are affectionately known as jarheads, and are far more intelligent, sophisticated, and attractive than the average newsletter reader or listener or viewer. If you wish to become a jarhead, please subscribe using this button:

• As a reminder, when this message is truncated in email, click on the title to open it in a browser tab formatted properly for both the web and mobile.

Humor in Technical Writing

As I’ve mentioned, I’m busy working on a new book for the Pragmatic Bookshelf with the working title, Adding AI to Java. As my editor was reviewing a few early chapters, she made an unexpected request. She suggested that to keep readers interested, I should consider adding more stories and humor to my writing.

You’re probably thinking, “Oh, Lord, no,” or “Does she have any idea what she’s asking?” or “Has she ever met you before?” I truly sympathize, but in an evil laugh kind of way.

For years, I’ve had a rule with my books: Keep the humor as unobtrusive as possible. With my first book, Making Java Groovy, I took pretty much every gag that ever worked in a training class and stuffed them into the footnotes. That kept them out of the way when a reader was trying to learn something, but also gave my non-technical friends something to look at when they browsed through the book.

For example, when talking about the Groovy JDK, I said there was no need to reinvent the flat tire, with the footnote:

*Reinventing the flat tire is what happens when you reinvent the wheel and get it wrong.

Or, later, when I included my book with some other Groovy books, I added:

*I had to find some way to include my book in that august company, just to bask in the reflected glory.

Or, when writing about Domain Specific Languages (DSLs), I added:

*Mandatory DSL jokes: “JavaScript is a DSL for finding browser bugs”; “Java is a DSL for generating stack traces”; “Maven is a DSL for downloading the internet.”

You get the idea. I really had fun with it, putting in my own opinions and references that could be ignored on a first reading. (You should see the puns I used when talking about the Spock testing framework. They practically wrote themselves. “Test well and prosper,” “Spock is a logical framework for enterprise testing,” or even “I have been, and always shall be, your friendly testing framework.”)

After years of both writing and teaching technical topics, there are two Guiding Principles of Humor that I live by:

• Most people (myself sadly included) are not as funny as they think they are, and

• If someone is confused, they don’t want to hear any jokes.

Keeping the jokes in the footnotes accommodated both principles. I really liked this approach. A friend of mine saw them and gave me the most back-handed compliment I ever received when he told me he loved that the jokes where in the footnotes, because that way he could skip them.

Gee, thanks.

I will say that humor keeps me motivated. If I have a gag to tell, I’ll write lots of pages just so I can tell it. Then, later, my editor can frown, shake her head, and tell me to take it out. Even so, that will leave me with all those pages. :)

When I shifted to writing for O’Reilly Media, my books were recipe driven (Gradle Recipes for Android, Modern Java Recipes, and Kotlin Cookbook). The recipes were all so short there really wasn’t time or space for jokes. The only real gag I used in talks later was based on the cover of Kotlin Cookbook:

In the colophon at the end, there is this statement:

The animal on the cover of Kotlin Cookbook is a kinkajou (Potos flavus), a long-tailed mammal native to Central and South America.

I had a non-technical friend ask (though I’m pretty sure he was joking) if the animal on the cover was a Kotlin and if my book was about how to prepare them for dinner. (As the meal, of course. Not as guests. Presumably.)

Of course I agreed. In fact, I got my local Barnes and Noble to carry a couple of copies. Then I took one out of the Computer section and moved it over to the Cookbook section to see what happened.

The result? A few days later it was back where it belonged. Oh well. At least I thought it was funny, but some gags are better when you do them than when you talk about them.

When I finally moved over to the Pragmatic Bookshelf, I hoped for a return to gags in the footnotes, but no. The rule for the Prags is that footnotes are only for URLs to external sites. Therefore, my two Prag books (Help Your Boss Help You and Mockito Made Clear) are seriously light on humor.

This week, however, I suddenly realized I have a perfect place to add jokes again. The book is all about adding AI to Java, so whenever I have a test case or other interaction with an AI tool, I now have an opportunity to “tune” the response as I see fit. For example, I just added this test case:

Now I’m having fun again. I’m busily rewriting earlier chapters to add gags. Just like we’ll do in practice when we insert AI-generated code that messes up, I’ll blame the AI if you don’t think the jokes are funny. That’s a win/win all around.

Gradle, Java 21, JUnit, and Reactive Spring

Please forgive this diversion into issues that may only matter to me, but in the off chance any jarheads care about this, I finally made all the Gradle warnings go away when I run JUnit tests using Java 21.

In your build.gradle file, add the following arguments to the jvmArgs method:

tasks.named('test', Test) {
    useJUnitPlatform()
    jvmArgs("-XX:+EnableDynamicAgentLoading", "-Xshare:off")
}

You should already have the call to useJUnitPlatform(), which means Gradle will detect JUnit 5 tests. The jvmArgs command gets rid of that warning about dynamic agents, which I don’t understand and don’t care about. When I got rid of that warning, it turned out I also needed the -Xshare:off flag set to get rid of the warning that replaced it.

If you are using the Kotlin DSL, here is the build.gradle.kts version:

tasks.test {
    useJUnitPlatform()
    jvmArgs("-XX:+EnableDynamicAgentLoading", "-Xshare:off")
}

Same thing, really.

Oh, and as long as I’m getting rid of Gradle warnings, if you ever use Gradle with Spring Boot and you add the webflux module (for reactive applications) and you’re on a Mac with Apple silicon, add this:

dependencies {
    implementation(
        'org.springframework.boot:spring-boot-starter-webflux')

    // ... other dependencies ...

    boolean isMacOS = System.getProperty("os.name")
                        .toLowerCase()
                        .contains("mac")
    boolean isAarch64 = System.getProperty("os.arch")
                          .equalsIgnoreCase("aarch64")

    if (isMacOS && isAarch64) {
        implementation(group: 'io.netty', 
                       name: 'netty-resolver-dns-native-macos',
                       version: '4.1.110.Final', 
                       classifier: 'osx-aarch_64')
    }
}

For one brief, shining moment, all of Gradle’s warnings will go away. Enjoy it while it lasts, because it won’t.

Now back to our regularly scheduled silliness.

Tweets and Toots

Slides

I had a new producer for an upcoming training course ask me to supply my slides a month beforehand so she could look them over. She also asked if I’d use their PowerPoint template.

I haven’t responded yet, because nothing good will come of that.

That’s just math

Hard to argue with that logic. See also, “AI capabilities, growing”.

SQL lesson

OMG, I wish I’d heard that years ago. Brilliant.

I find this statement offensive

That’s a really good lesson to keep in mind over the next few months.

The very model of a post

Um, rhyming cacophonous with words? Nope. Otherwise, excellent job.

I asked GPT-4o to fix it, and here’s what it generated:

I cannot stand the parodies of modern major general,
They're overdone and simply not as good as the original.
They've done them about everything, whatever topic, big or small,
And when I notice one of them my eyes will always start to roll.

The diction's always slurry when they rush the complicated words,
And adding many fricatives will turn it all so quite absurd.
The slanted rhymes are silly and they keep just making more and more,
Please someone stop the parodies of modern major general.

The scanning of the lyrics in the meter is unbearable,
They emphasize the syllables in ways quite untenable.
In short, in matters musical, prosodic and ephemeral,
I cannot stand the parodies of modern major general!

I’m teeming with a lot of news, with many simple facts about the square of the hypotenuse. Also, “sat a gee” means to ride a horse, and that would actually rhyme with cacophony, but we’ve already pushed this too far.

Incidentally, if you ever get a chance to watch the Pirates of Penzance movie with Kevin Kline as the Pirate King:

Run, do not walk, to see it. It’s truly awesome, and he’s the best Pirate King I’ve ever watched. Angela Lansbury was very good, Rex Smith as Frederick was okay, and I may be in the minority when I say this, but I really enjoyed Linda Ronstadt as Mabel. George Rose as the Modern Major General was excellent, too. Seriously, that’s the best movie version of anything Gilbert and Sullivan related ever.

Let them eat cake

Yeah, some assembly required, and the instructions are in Swedish.

Saved by pedantry

An old gag, but a good one.

Have a great week, everybody!

Last week:

• Latest Features in Java, an NFJS Virtual Workshop

This week:

• Week 1 of Spring in 3 Weeks, on the O’Reilly Learning Platform

• Practical AI Tools for Java Developers, an NFJS Virtual Workshop

• Gradle Fundamentals, an NFJS Virtual Workshop