Great Quote About Tests by Uncle Bob

Robert “Uncle Bob” Martin is a programmer’s programmer. He’s been called a Master Craftsman. And he likely deserves even more respect and admiration than that.

Here is a great quote from an entry titled First on his blog:

Well designed tests are small isolated snippets of code that call into the system being tested, expecting certain results. A programmer can read the tests to understand what the tested code is supposed to do. So the tests are documents. They are written in a language you understand. They are utterly unambiguous. They are so formal that they execute. And they cannot get out of sync with the application.

What an awesome way to think about tests.

My all-time favorite Ron Jeffries Quote

My favorite Ron Jeffries quote, from the NeverIsNeverNever page on the C2 wiki:

I know that if you agree NEVER to let the unit tests drop below 100%, you’ll only do it that one time when you just couldn’t figure out an incremental way to change all the deductions from negative to positive. If you agree NEVER to keep a task open for two weeks, you have a better chance of finding the way to do it incrementally, and that one time you’ll make sure you’ve sucked every idea out of the universe before giving in.

When I say something should never be done, it should mean that you’ll never do it unless you really have to.

And if you really have to, you’ll ask everyone you know first so you still won’t have to.

And if you still have to, you’ll be looking over your shoulder scared to death that I’m going to materialize there and say “why didn’t you just…” and be RIGHT, and EVERYONE will know you’re an idiot.

When you’re sure that you’ll be able to say “because X” and I’ll quietly lower my eyes and say “oh” and de-rez back to wherever I come from … then break the rule.

Then do one more thing. When it’s over, and you’ve suffered – as you will – for breaking the rule, think back and figure out what you could have done, and learn the deeper meaning of NEVER.

Always Valid

(One from the archives. Not sure when I wrote this. I think it still stands.)

These days, with the rise in programmer testing (also known as unit testing to its friends) much testing effort is put into ensuring that program logic is correct. This is good and to be encouraged at all times. A program that does the right thing is always more likely to be correct than one that does not. Interestingly, with all of this new-found enthusiasm for testing, there seems to be a few gaps in our approach. The one I’d like to discuss here is the principle of “Always Valid”.

This principle is easy to arrive at from first principles. You see, programs do stuff. Every programmer knows this. We know it because we’re the ones that tell them how to do it. But pause a moment and consider what this “stuff” is most of the time. The vast majority of the time we’re processing data; and it’s the data that is the star of the show. Our programs are just descriptions of what we want to do to that data. The data is the important thing.

Given that we care deeply about the data, we should be careful to ensure its quality at all times. We need to not only care about it when we’re processing it, but both before and after. At any time that data is in the gentle “hands” of one of our programs, we need to treat it with the respect that it deserves.

If you ever think that data isn’t that important, ask some of your business users if they would rather lose their invoice file or the program that processes it. I bet they’d take the approach that something could be hacked together to process the file if they ever lost the program, but there’s no way to recreate invoice data without a backup. So, data is always more important than mere code.

How do we treat data with respect? If the stuff is so vitally important, how does this knowledge affect our behaviour? We respect data by ensuring that it’s always valid. Period. It’s as simple as that. Well, it’s as simple as that, to say. Naturally there are some technical details that we need to take care of on the way to fulfilling the “always valid” principle, but these details are not that complicated and bring about a massive improvement in data quality for quite a small amount of effort.

At All Times

The zeroeth step, more of a guiding principle really, is the determination that your value objects will never be in an invalid state. This directive guides everything else that you’ll read here. An object may be in only two states. It can be null, i.e. it doesn’t exist and therefore has no data to worry about, or it can be instantiated and be in a valid internal state (however that is defined for the value object you’re working with). Nothing else is acceptable if we are to achieve the level of data quality we’ve already outlined.

This may seem like an overly strict restraint, but consider that in these days of multi-threaded applications, it’s possible that another thread is accessing your object when you don’t suspect it. So, if you have an object that you’re initializing and you have any intermediate steps, that other thread may access your object before you have it finished. This will almost certainly cause data quality issues, perhaps even data corruption.

Understand your data

The first step to data quality is to understand the data. It is especially important to understand the relationship between the different attributes. For example, when dealing with a rectangle object, it’s likely to have two attributes and they’re likely to be length and width and they’re both vital to understand that rectangle.

Another example might be a person object. Now, I know that people objects can be complex, but let’s say that we have a simple one and that we’re just describing people we know. Attributes like gender and name are going to be important, but under most circumstances, it is not necessary to know someone’s birthdate.

I can offer you a humorous personal example about birthdates. Ever since I was old enough to fill out forms, I have been listing my mother’s age as “OVER21″ because she never told anyone how old she was. Apparently, her age was unimportant for all of my interactions with government agencies, even when applying for clearance under the U.K. Official Secrets Act so that I could have an internship at a British Royal Navy establishment! (This used to be legal in England. I have no idea whether it still is, or whether listing your date of birth as “OVER21″ is legal anywhere else in the world. And I am absolutely not a lawyer.)

Understanding our data, we can now implement that understanding in our value objects. If I’m creating a rectangle object, I’m going to want both the length and the width for my object to be valid. If I have one without the other, or even neither, then I do not have a valid rectangle.

Building our value objects

There are two ways to fulfil this data relationship requirement. The first, and my preferred approach, is to fully construct and initialize an object in its constructor. Our rectangle object needs two fields, so it has a constructor that takes values for those two fields and initializes the new instance, making it valid right from the start. Naturally, this would mean that there was no default constructor, unless the value object really did have no required fields, but I consider that unlikely.

An alternative method of creating valid objects is to use a factory. The reason that I don’t recommend the factory approach is that the factory still needs a way to create the object and ensure that it’s correct from the start, so it’ll most likely need to use the appropriate constructor behind the scenes anyway. Cut out the middle-man and just create the object yourself!

Updating value objects

Updating a value object is an opportunity for making a value object containing invalid data. Consider implementing value objects as immutable objects. This eliminates the opportunity for them to become invalid during updates. New versions of the objects can always be created with the new data, so it’s not a huge roadblock.

If you do decide to allow updates to your value objects, please consider an update method that will update everything that needs updating together all at the same time. In this way, you reduce the update to something approaching an atomic activity and reduce the danger of the object being accessed while it is internally inconsistent.

Validation

Lastly, it is vitally important to remember to validate data on the way in to an object and throw appropriate exceptions if the data isn’t correct. Validate everything that you get in the arguments to the constructor. It’s valid to throw exceptions in constructors if you receive bad data. The exception will prevent the instance being created and so protect the caller from receiving an invalid object.

Conclusion

By following the advice here, you will be on the way to the creation of high quality data value objects. These value objects will play a major role in your quest for data quality. Now, your programs will do the right things and do it with data that is right. What’s not to like?

Where Is My Global Warming?

Sitting here in lovely Dodgeville, WI with the temperature at 2 degrees Fahrenheit and a windchill of -10 degrees Fahrenheit, what else could my thoughts turn to than global warming? As I am sure is true of many of us in the Upper Midwest, I am quite keen on the idea of global warming. I want some global warming. The problem is that I’m not seeing any. None, nada, zip.

And it would seem that I am not imagining this lack of blazingly warm temperatures. Here are a few headlines that I saw linked from the Drudge Report today and an extra one for good measure.

“Global Sea Ice Breaks Record High For The Day”

“Dueling Datasets: Satellite Temperatures Reveal the ‘Global Warming Pause’ Lengthens to 18 years 2 months – (218 Months)”

“Carbon dioxide emissions help tropical rainforests grow faster: Study shows trees absorb more greenhouse gas than expected”

Mechanics Of Writing A Book

I have always loved books, so the thought of writing one (or more) has never really been far from my mind. I have been fortunate to have been on the side-lines of the publishing business for a few books, so that whet my appetite even more. I have been a pre-press technical reviewer for a handful of technical programming books from publishers that there’s a good chance you’ve heard of. I have also been a book reviewer for the Slashdot website, where you can find at least two dozen reviews written by yours truly. These activities were a source of encouragement to learn more about books.

Fiction Or Non-Fiction?

I suspect that fiction is the hardest kind of book to write because you not only need to know how to write, but you also need an imagination that will provide you with what to write. As a computer programmer, my imagination is pretty limited, so that leaves non-fiction. Then there is the choice of topic. As a computer programmer and a pastor, I could write about a number of geeky or theological areas. In the end, for my first book, I went with theology and Apostolic Baptism was the result.

Publisher Or Self-Publishing?

The next decision was whether to self-publish or to seek a publishing house to accept a book proposal. Working with a publishing house brings certain benefits and while many of those are attractive, the chances of most authors being accepted is pitifully small, especially if you are not a known name in the writing world. Further, most publishing houses look for more than just an intended outline of a book, they ideally want to see several chapters, at least three, completed to proof-reading condition, before they will commit to your book. As my intended book was not likely to be that large (it came in just under 100 pages in the end) those three chapters would be a reasonable portion of the finished work, so I might as well just keep going by myself after the first three chapters and do it all myself.

Interestingly, I have seen a number of authors start with self-publishing and then get recruited by a publisher when they see the quality of the finished work. In many ways this seems to be the best of both worlds. The publisher gets a book that they can see is a quality work before they pay the author anything. The author gets to deal with a publisher from a position of influence that most new authors do not have and this often results in a better deal for the author, especially in the area of retaining the electronic publishing rights to their work.

Choosing LeanPub

As a geeky kind of fellow and a computer programmer, I have always liked the idea of ebooks. I’ve also got quite an enthusiastic inner-typographer. So whatever solution I went with was going to have to try to satisfy both of these needs. One of the natural tools for producing high-quality printed output is LaTeX. Sadly, it doesn’t work so well with most ereaders. I needed something that could produce ebooks and LaTeX quality printed material. And if it could handle Markdown as well, that would be perfect. I was already using a tool called Pandoc for my sermons, so I wondered if I could use that to create my book. The answer was yes, but there would be a lot of configuration required to get everything looking high-quality. Somewhere around this time, I came across LeanPub and my problems were solved.

LeanPub is an online service for authors where you create books using Markdown, or more specifically Markua, which is a superset of Markdown designed for book publishing. The output from LeanPub is produced in three formats: PDF, EPUB and MOBI. Their book templates are gorgeous and look like they’ve come straight from a high-end book publisher. Even better, they also have the option to produce a high-quality final print PDF that can be directly uploaded to any number of printing services to produce the finished paper book. I was ready to pull out my credit card, but their price is free for the services, only taking a slim commission if you sell through their website.

I am very pleased with the results that I received through LeanPub for my first book and am now in the process of creating more books through them. Understand that I have no business relationship with them, beyond being a satisfied customer, so please take my strong recommendation to look at their services as an honest attempt to steer you right and not to make money off of you.

Organizing Your Book

There are traditional ways of organizing a book that very few people could articulate, but that they would notice immediately if not followed. I found a lot of this information during my initial search for LaTeX stylesheets that would help me with my initial thoughts of self-publishing. While I did not ultimately use those style sheets, the information provided about book layouts and structure were invaluable.

I recall that the most useful LaTeX stylesheet was Memoir. It came with a 600 page user guide, beautifully typeset using Memoir and the guide contains a significant amount of information on how to layout and organize a book. Only after this was explained does the guide proceed to explain how to use Memoir to achieve said layouts.

Content

For a non-fiction book, it’s important to plan your content and ensure that your approach to the subject makes sense. I worked with my Presbyter (a pastor over pastors) to ensure that my approach was solid. I also had a safety net, because one of my proofreaders was also a Presbyter (for a different section of the state) and he verified that I had not made any mistakes with my doctrine. Knowing that I’d verified these points with knowledgeable men was a great relief for me.

The Actual Writing

Writing is hard. And good writing is very hard. And Jerry Pournelle says that if you want to be a real writer you must write and throw away a million words. A book is not the best first writing project for most people. My preparation for writing a book was to have blogged for several years and having written an average of 40 sermons a year for seven years. That amounts to a good number of words of practice.

Proofreaders and Copy Editors

I cheaped out here and skipped retaining a copy editor. I think I got away with it for two reasons. The first reason is that I am pretty picky with my own writing and will re-write a sentence if I don’t like it. And I re-read everything the next time or two I come back to it. I write with my spell checker on and as part of getting ready to send copies out to my proofreaders I ran the entire text through the Hemmingway App. I didn’t follow all of its advice, but it did cause me to consider every sentence in every paragraph to ensure that they worked well together.

Having skimped on the copy editor function, I opted for plenty of proofreaders. I had five proofreaders lined up and got two and a half out of five worth of proofreading. Life happens, so with more proofreaders, I still received a good quantity of proofreading with two of the folks needing to bow out. My two primary proofreaders were published authors and one of them was also a school teacher. One of my proudest moments was when the school teacher handed me back a marked-up copy of the manuscript and told me that there weren’t as many errors as she had expected.

Printed Proof Book

The next step was to create an account at CreateSpace and upload my manuscript. I selected a free cover layout and uploaded my own photographs for the front cover and author picture. Then it was a very simple affair to order a couple of print proofs. Even with postage, this step cost me less than $10, so my financial investment so far is still minimal. The proof books arrived in less than a week and I was greatly impressed by the quality. I had expected there to be an obvious indicator of the proof status of the book, but the only indicator was the word “proof” on the last page before the back cover. The cover print quality was excellent, the binding was solid and the inner manuscript looked just exactly like the high-quality PDF that I had generated from LeanPub.

I took the inexpensive road on the matter of an ISBN. International Standard Book Numbers are expensive in small quantities, so I took advantage of the offer from CreateSpace to assign me one of their ISBNs for free. If I were to ever sell this book through another publisher, I would need to get a new ISBN myself or through the other publisher. At this time, as I still retain all copyrights to the book, I’m not overly worried about this and will revisit the decision should the day come when I sign up with another publisher.

Publishing

The act of publishing your book after you have reviewed the proof version is very straight forward. You just press a button to assert that you accept the proof version. Congratulations, you have published a book. There were more questions after that, but these are all to do with sales channels. At this point, you may now purchase completed copies of your book directly from CreateSpace. After carefully working through the sales channels questions, I just needed to wait a few days (turned out to be closer to a week) for my book to be available through Amazon.com in print or electronic versions.

Conclusion

My conclusion is that self-publishing a book is within the grasp of almost anyone with a computer, an Internet connection and the willingness to learn a few simple new skills. The process was greatly simpler than I had feared it would be after reading up on how to use LaTeX to create your own books. LaTeX is great, but for books that will also be targeted as ebooks, it is less helpful.

I am very pleased with the tools available online for either free or an inexpensive amount. LeanPub is a great service and I recommend them heartily for creating the book and selling electronic versions. CreateSpace printed excellent quality books in a Print On Demand fashion and I am very pleased with my resulting product.

If you feel that you have a book within you that is just itching to be written, now is the best time there has ever been to bring it to fruition.