Rationalizing the choice of ruby for code examples

I am writing copy for a technical book that will present concepts predominately as example code in the Ruby Programming Language.

I recently explained the concept to some old colleagues which resulted in a discussion on the rationale for selecting ruby over math, pseudo code, or no examples at all. I'm not even going to try to justify the choice objectively (perhaps parsimony, prominence, popularity, etc.), rather I'm going to discuss some factors that influenced the decision.

It is a book by a programmer for programmers, that is people used to thinking about systems from a computational perspective. It is a natural fit therefore to communicate computation notions programmaticly. Further, to do so with small, sharp, and executable code examples ultimately makes the end product more engaging (at least it does when I project myself as a consumer).

Firstly I chose code examples over mathematical expressions. Equations can present concepts very compactly although generally at the cost of time and readability, at least for the types of things I'm interested in (systems and procedures). I made the same decision to use code snippets to express concepts in my dissertation, primarily because I felt a snippet was faster to write, faster to verify, and easier to read.

Secondly, I chose code over diagrams because I find most diagrams for conveying computation to be wasteful with regard to space and time. They have their place in design, but when communicating a programming concept I prefer short and sharp code snippets of conditional execution paths or an object and its use, over flow charts and class diagrams.

Given that I decided upon code examples, I chose to write snippets in a real language over a fictitious one (pseudo code) because I want code that can be executed. This is a no brainer, executable code adds substance to examples for the reader and provides an important verification step into the production of copy. The important decision here is the choice of language for general readability by programmer types.

I chose Ruby primarily because it is concise and reads well, two features it shares with pseudo code. The ruby syntax is quite general for modern languages, and procedures almost read like conversations between entities. The conciseness and readability come in part from the mixture of procedural, object-oriented, and functional features it supports, the blurred line between expressions and statements, and the fact that it is dynamically typed. Further, programming in Ruby "is fun", which is not surprising given that it was principled to be productive and enjoyable for programmers to work with.

To recap: code over mathematics for readability of computation, code over diagrams for conciseness, real over fictitious code for executability, ruby over other languages for its power and generality of syntax.

Ruby is a moderately popular language, although more readers will be unfamiliar than familiar with the specifics of its syntax. This can be addressed by providing a primer of 'Ruby for programmers' in the book, and limiting the use of features that do not align to the average C/C++/C#/Java programmers world view. It seems that a fine balance must to be negotiated here because constructs like closure's can significantly simplify examples in some cases. This is an important caveat to acknowledge because examples in a non-milk language (C or Java) may have been a deal breaker for the younger less experienced me of ten years ago.

Ruby does have some criticisms over other languages, the most relevant of which is execution speed. Some ruby interpreters are faster than others (checkout this great shootout), although ultimately the executable ruby examples are intended for education, not production. Speed of execution is happily sacrificed given that the intended readability of examples means code can be realized on demand for a problem and language of choice.