Agile Java Rewrite?

I’ve had the idea to write a book on refactoring for some time, and even produced a proposal a couple months ago. The focus would be “refactoring in the context of TDD,” aka continual design. I only got halfway through a sample chapter, which the publisher requests. (Writing the sample also reassures me it’s the book I want to and can write.) This past week I heard that a Big Name is currently working on a refactoring book rewrite. Hmm, maybe this project is not something that I should be doing.

Agile Java has been in print since 2005. It still sells copies–not a lot–and I also still receive thanks for the book from many folks who found it a great way to learn (TDD + OO + Java from the ground up). I feel a bit guilty that people still use a 12+year-old-book featuring a version of Java end-of-lifed for about 8 years! Time for a rewrite, as some have requested?

A dozen years later, what would change?

  • New approach based on new versions of Java: The book was written to coincide with Java 5 and its dramatic language changes, which also made it easier for a simpler, more-OO focus than previously would have been possible. With Java 9 on the horizon (July 2017, maybe?), a new version would find lambdas being introduced fairly early to allow new developers to focus on the value of more-functional approaches to solving problems.
  • Potential new “Additional Lesson” chapters focusing on full-stack considerations (HTTP and JPA, for example)… or maybe this whole notion of covering peripheral technologies gets dropped. Yeah, let’s do that, and keep this to a somewhat-reasonable length.
  • Updated for the latest version of JUnit (5).
  • Use of fluent assertions (probably Hamcrest with mention of other frameworks).
  • Emphasis on one behavior per test, as well as the value of tests-as-documentation.

Otherwise, the tone and general flow would remain the same. Hopefully not the page length: Few folks want to read 750-page books anymore.

I’m the sort to find the stuff I wrote a while back to be lacking, so I might be tempted to rewrite a few things…

“TDD Is Not a Silver Bullet”

As a writer, I’ve left a few incomplete efforts by the wayside, promising I would someday return and complete them. The one I feel most guilty about is an interview with a promising young developer named Tim.it's a gold bullet... get it?

In 2006, I had helped train and coach a development team in TDD at a large corporation’s headquarters in the U.S. In fact, the training and coaching were separated by a month or so. I initially worked with a cool manager who brought me in to run training, but by the time I returned for the follow-up coaching, the manager had departed. In his place was a humorless, dictatorial manager. While working with the team, I focused primarily on helping the individuals see how TDD might help them build quality software. Unfortunately the temperament of the manager meant I departed with few hopes for the success of agile or TDD at the team level.

When pairing with Tim, I could tell he was very sharp but also very skeptical and resistant to TDD. Two years later, I received an email from him. He had some interesting things to say. I asked him some questions on TDD, with the intent of shaping it into an interview I would publish. He asked that I not mention the company at that time. Well, four years later, I still think these are wonderful answers, and so I plan on publishing them over a couple or more blog entries. (Tim–sorry I took so long!)

Here’s one of the questions and answers from Tim.

Q #5. What did you finally see or recognize in TDD that you initially couldn’t see?

A.  I have somewhat of a loaded answer to this question.  I’ll preface with this… I didn’t go out and research TDD on my own.  I had never heard of it, or knew what it meant.  I wasn’t chomping at the bit to change the way I had been writing code for the 5+ years before that.  It was directed from the top down in my organization, and my team was a test bed, so to speak.  Right off the bat, I had preconceived notions as to why I had to learn this approach, but why should I?  So I had no expectations as to what I was supposed to see other than tangible things that management probably thought were the only byproduct of TDD (i.e. JUnit/HttpUnit test cases).

So I can only answer your question with what I have found with using the TDD approach.  It’s rather simple, and yet not so simple.  I have to bullet them:

  • I have found myself writing cleaner, more efficient, maintainable, and better “architected” code.
  •  I have a better understanding on topics as simple and innate as the Java specs, to more complex such as patterns, writing frameworks, and abstraction.
  • Some would laugh, but I never followed the whole “code to the interface, not the spec” statement.  I cannot imagine not following this now.
  • My skills with the editor I use have become extremely advanced.  So much so, that I would challenge anyone who claims TDD will slow you down that I can write the same thing simpler, faster, and tested.
  • I automatically have a spec/documentation (the test cases) since that’s where I start.  Any developer who says they keep up with documentation is flat out lying!
  • I have more confidence.
  • I have the feeling of “getting it”.
  • And I have more fun.

I can admit that I didn’t fully understand TDD until a couple of years ago. So if you do the math, it took @2 years to really sink in, but I know I am better now than I was then (and I thought I was pretty damn good).  I can only surmise that in 2 more years, I will feel the same compared to now.

By no means am I saying that I can solve any and every development endeavor and never get frustrated or challenged, all because of TDD. Development is challenging. If I didn’t get challenged than I would probably, really hate my job. I could do without the frustration, but that goes with the territory… and builds character.  I feel like I have to say this because (and I think I mentioned it before) some developers I talk to think that TDD is a silver bullet to solve these issues just because you have some test cases and a build server, and as you can see (I feel) it’s much more.

One thing that stands out for me is Tim’s notion that he has “more fun.” More on that in an upcoming post.

Collaborative (Dare I Say Pair?) Writing

I enjoy writing, though I’m not as prolific as I’d like to be. I tend to re-read what I wrote many times, often second-guessing it. Like any writer, I also find difficulty from time-to-time, getting stuck on how to phrase a paragraph or a sentence. I’ll typically mark things and return to them later. All-in-all, I can slam out text, but getting polished product out the door can be challenging.

ball point pen writing
source: https://commons.wikimedia.org/wiki/File:2004-02-29_Ball_point_pen_writing.jpg

I read and enjoyed Weinberg on Writing: The Fieldstone Method when it came out. I already had been employing its core idea to an extent: capture thoughts as they arise (index cards work great!), then incorporate them as appropriate in an article or book. Each idea on a card might act as a central idea around which writing can build, or it might be used to fill in a “hole” in the text. Emphasizing this technique has made writing a lot more fun, and I tend to not lose great thoughts that had popped into my head.

My best writing experience, however, has been collaborating online with Tim Ottinger, originator and co-author on Agile in a Flash. We had a slow winter–after writing a pile of articles for PragPub, we both got very busy with work, and did little writing. We finally found some time to commit to delivering a new Agile in a Flash post, Is Your Unit Test Isolated?

Two days ago, we got our headsets on, started up a Skype conversation, and talked for a few minutes to agree on what we’d work on. We started some single-threaded editing on a very rough draft at Blogspot, but that wasn’t effective, so I pasted it all into a Google Doc.

Google Docs doesn’t provide the best document editor in the world, but it is highly effective for collaborative writing. You can see each others’ cursor and typing as it occurs, and you can look at offline revisions if necessary for comparison.

Mostly we’re not talking via Skype (and in fact sometimes we’ll collaboratively edit without a voice conversation at all). Instead we’re communicating through the document. Tim will start re-working a paragraph that I might have just finished writing, and I’ll get out of the way. Sometimes I’ll watch and toss in a comment–just typing it right into the document–and other times I’ll go off and stab at a paragraph that Tim wrote. Or I might go off and re-read the document, looking for flow and completeness problems. It’s pretty haphazard, yet it works, and it’s fast. We might go back and forth at a paragraph a few times before we figure it works.

Collaborative writing works best if you grow a layer or two of skin. We’ve learned to be pretty direct: “[[ I don’t like that ]],” Tim might type (the brackets are our way of setting off comments). Ok! Good technical writing requires harsh critique. Better Tim drop a pointed comment than a few thousand readers.

At times I’ll return to find something I’ve written completely gone or gutted and rewritten. It was a little disconcerting at first, but I’ve learned to trust Tim’s reworkings. I can always look at the old revision if I thought an important idea got deleted.

The unit test article took us about an hour to get to 98%. We let a couple outstanding concerns sit for a few hours, made some offline changes, and published it the following morning (yesterday).

As with pair programming, I’ve found such highly collaborative pair-writing to go much faster than writing on my own, and produce a far more effective product.

TDD for C++ Programmers

C++Recently I’ve been getting a good number of calls from C++ shops interested in doing TDD, despite my heavy Java background. I took on some of the business and had to turn away some to avoid being swamped. Many other folks I know (name dropping time!)–Tim Ottinger, James Grenning, JB Rainsberger, others–have also reported doing C++ work recently.

Is TDD finally taking hold in C++ shops? Does TDD even make sense for C++? I think so, and two current customers believe they’ve been seeing great benefits come from applying it. Building and delivering a C++ TDD course recently helped me come back up to speed in the language to the point where I was comfortably familiar with all of the things I hated about it. 🙂 It makes no sense to take such a difficult language and stab at it without the protection of tests.

I’ve been simultaneously writing more (after a typical winter writing freeze) and looking at Erlang–a much cooler language, challenging in a different kind of way. Meanwhile, my editor at PragProg has been asking for new book ideas. Here were some of my thoughts:

  • Refactoring 2012
  • Modern OO Design (not template metaprogramming!) / Simple Design
  • Object-Oriented Design “In a Flash” (card deck, like Agile in a Flash)

No matter how hard I try to run screaming from C++, there it is right behind me. It’s indeed a powerful language, and there is gobs and gobs of code written in it, and it’s about time we started trying to figure out how to make the best of it. It’s not going away in my lifetime. I also think C++ programmers are not well-served in terms of writings on TDD out there.

So… I decided it was going to be TDD in C++. Tim Ottinger and I put together and just sent out a proposal for a book tentatively named TDD for C++ Programmers (with a catchy subtitle, no doubt). We hope there’s enough demand and interest to get the proposal accepted. If all goes well, we’ll be soliciting reviewers in a few weeks.

I look forward to writing again with Tim! More in an upcoming blog post about our collaborative writing experience.

Don’t Stop Reading…

When writing, be careful of presenting an opposing point first with the notion that you’ll make your counterpoint in a subsequent paragraph or page. That first pitch is often as far as some readers get. Royce’s article “Managing the Development of Large Software Systems” led to decades of waterfall for this reason.

Recently, a pair-developer expressed concern over the use of multiple returns in a short method. I said I knew about the long-standing rule but that it created little value for very short methods. Two days later, I heard the same concern during another pairing session. Twice in one week? Curious!

I asked where they’d read about the rule. “Uncle Bob’s Clean Code” was the surprising response. “Hand me your copy!” I insisted, a bit worried, and quickly located the text in the functions chapter. The very last paragraph on page 48, starting a new section, states: “Dijkstra rules of structured programming… [say] …every function … should have one entry and one exit. Following these rules means that there should only be one return statement in a function…” Oh! Yeah, I learned that 30 years ago. Really, Bob?

Page 49, top paragraph: “”While we are sympathetic to the goals and disciplines of structured programming, these rules serve little benefit when functions are very small. It is only in larger functions that such rules provide significant benefits.”

Oh, ok. Whew! Crisis of faith averted.

Readers: Inattentive reading can be embarrassing!
Writers: Don’t assume readers will get to your point. Make it first.

A Note on the Old Blog

I converted to WordPress some time last year, since Blogger killed my ability to edit there and post on my personal site. In the meantime, I have two annoyances: One, the spammers to this blog are unrelenting. You don’t see any of the spam comments, but I get an email for each one (it could be a real comment) and have to whack about 25 spam messages a week.

Two, while it looks like it’s possible to add comments to my old blog entries, they really just disappear into a bit bucket somewhere. I might dig around and fix the page so it no longer supports typing in the comments, but in the meantime I’ve had two comments that I wanted to respond to, and have felt guilty because I can’t do so easily.

Perhaps my responses will end up as blog entries.

Blogger -> WordPress

Until recently I used Google’s Blogger for creating posts and publishing them to my site via FTP. Google decided that they wanted to focus support on blogs hosted by them and on blogs existing on a custom domain, claiming that the FTP solution was too much trouble to support. Unfortunately, they provided no solution for seamlessly meshing their blog product with my existing site.

I’ve decided to move to WordPress, since it’s the only one of three solutions provided by my ISP that is familiar. This will be an incremental exercise. I hope I can customize WordPress enough to make for a seamless look. Short-term, I’m sure it’ll be a bit rough. Tips and suggestions welcome.

Convention and Case

I’m learning Grails. I found a good tutorial written by Jason Rudolph. It does a great job of covering a broad range of the typical things you’d want to do in putting up a quick web site.

Unfortunately, it’s for an older version of Grails, but so far that hasn’t been a barrier; most of the changes I need to make are self-explanatory. I’m almost finished, and feel I have a good grasp on using Grails.

Still, I struggled for about two hours last night on a problem in going through the tutorial. Here’s a form I defined.

<g:form controller="user" method="post">
    ...
    <g:actionSubmit value="Log In"/>
    ...
</g:form>

And here’s some of the controller:

class UserController extends BaseController {
  def beforeInterceptor =
 [action:this.&auth, except: ['login', 'logout']]

  def index = { redirect(action:list,params:params) }

  def allowedMethods = [delete:'POST', save:'POST', update:'POST']

  def login = {
   // ... 
  }
  // ...
}

I think that’s all that’s relevant to show. Those of you who know Grails know how the form knows which controller method to call; I wasn’t paying enough attention and missed the simple cause of my problem, which was that a simple form submit from the login page kept generating a 404, URL not found. It showed me the request URI:

RequestURI=/racetrack/user/index

Yet that is a valid URI (index redirects, of course). In fact, if I copied the URL grails generated, and pasted it into the address bar, the proper page came up. I tried a few things, including explicitly specifying the action:

<g:form controller="user" method="post" action="login">

No dice, same problem:

HTTP ERROR: 404

NOT_FOUND

RequestURI=/racetrack/user/login

Frustrated, I tried a few other things. Still no dice. I looked at the HTML provided in the book and looked to ensure I typed it correctly (I almost always type my own sample code rather than paste it, I learn better that way). Looks pretty much the same. Web search, no exact match on my same problem; found a couple odd things that it might be, tried ’em, not the problem.

When in doubt, really make sure you have exactly the same thing. Whitespace and case. Case couldn’t possibly matter on button text, could it? Well, yes, especially when you follow this notion of programming by convention or programming by default or whatever you want to call it. An actionSubmit defines the controller method, either explicitly or implicitly. Explicitly, you can simply say:

<g:actionSubmit value="Log In" action="login"/>

In the absence of the action attribute, it uses the value attribute. Apparently, it lowercases the first letter for you, but then simply removes spaces, not lower-casing any subsequent letters. Thus it was looking for a controller action named “logIn,” apparently. The tutorial code has it typed as “Log in.” I typed it “Log In” (I thought it looked nicer). Harumph.

Dumb on my part, for not paying enough attention to how the form was supposed to figure out which controller method to call (I hadn’t figured this out yet, and thought this was another “by convention” element, perhaps from somewhere else). Dumb on Groovy’s part, for not showing me the URI with the improper casing.

Lesson for me: Pay more attention. Lesson for tools that play by convention: If you’re going to do something as clever as use button text to define an action, make sure you are picky about case everywhere, and make it clear from whence that action name came (i.e. better error messages). Lesson for tutorial writers: It’s hard work to write a great tutorial. A good one gets you through all the happy path circumstances. A great one helps you out with all the dumb mistakes you’ll inevitably make.

Clean Code

Uncle Bob Martin just completed a draft of Clean Code, which the publisher site lists as being available August 22, 2008. The book is a code-intensive collection of thoughts on how to keep, well, your code clean. I was honored to submit two chapters, one on “clean classes” and one on emergent design. Uncle Bob got the last word, putting in even more code than I’d laid out on these chapters.

Many of the chapters are contributions by other current-and-ex-Object Mentors, but Bob put in a significant effort to go through the compiled book as a whole, to make sure everything coheres well and put his personal stamp on it.

The announcement got me stoked again about writing. Developer.com is also looking to compile an e-book of my many articles on design patterns (most with a TDD bent), so look for that in the near future. Still, I think it’s time I went back and started on a whole, real book of my own. The C++ tome is still a potential if Mr Koss and I can find mutual time together for it.

Comments and Footnotes

Will I ever stop railing on about comments? I don’t think so. As long as it’s possible to write code in a less than clear manner, people will always be compelled to explain their coding deficiencies. And I will always be compelled to resist.

As a writer, I try to ensure that the main text in a book or article is clear to the reader. Every rare once in a while (perhaps a couple dozen times in a book), I feel compelled to write extra information, something that supplements the text. I do so in the form of a footnote. The footnote provides non-essential information. It’s something that might help add some insights to what I just wrote, perhaps, or a humorous but otherwise distracting note.

My editors would never let me use footnotes to re-explain a passage of text. A coder attempting to salvage bad code with comments is like me adding footnotes to try and explain poorly written text. If the mainline text didn’t explain it well, why should a footnote explain it any better?

Footnotes and comments are ultimately a distraction. Ever try to read a book with footnotes on almost every page (and I’m not talking citations or references)? You may as well be reading two books, in some cases. As writers, we owe it to our readers write more clearly and to minimize these distractions.

 

Comments:

Excellent analogy Jeff.

Today I was asked what I think about assertThat for jUnit4 framework. It brings nothing more than a little bit more verbosity for tests, but won’t help people write better tests. Those , whom tests are of a poor readability and quality will remain the same with a new constructions, too.

Atom