Code And Cocktails

Reminder: Agile Is Risk Management

| Comments

In a note of the References section of “Waltzing with Bears” (DeMarco & Lister 2003), there is a note on “Planning Extreme Programming” (Beck & Fowler 2001) which says “When viewed as a set of [Risk Management] strategies, XP makes all kinds of sense.” This made me review how XP (or Agile more generally) is a risk management technique.

The incremental approach of XP reduces risk of late delivery or wrong delivery. The demo, planning and retrospective meetings seem to be an implicit risk analysis/mitigation exercise. It might be beneficial to make this more explicit.

One place where XP doesn’t line up with DeMarco & Lister’s thoughts on risk management is their advice that there should be sizable up-front design and estimation. XP eschews this. XP argues that the cost of up-front design & estimation of higher than the risk that they mitigate. It seems a reasonable risk vs. cost choice. Adding some explicit up-front brainstorming should be sufficient to cover the problem of missing large-impact risks. Furthermore the iterative nature of the methodology allows for a just-in-time approach to the costs and risks.

The book also contains a quote from Tom Glib who said (paraphrased) ‘Be ready to pack up whatever you’ve got any given morning and deliver it by close of day’. This is very fitting with the idea in XP that the result of every iteration should be deliverable and producing value. While a one-day iteration, as implied in the quote, is perhaps too extreme for many teams; the exercise of determining what it would take to deliver value in shorter and shorter iterations is valuable.

Bootstrapping a Testing Library

| Comments

Abstract

What’s a person to do when one prefers developing in a TDD style and decides to start a project where nothing not directly in the language needs to be written? Why, write a testing library of course! But… without a testing library how can one write this testing library in a TDD fashion? Herein is how I went about doing it.

(Full disclosure: this is not the first time I’ve tried this sort thing1. But I had forgotten I had done it before until I was writing this article.)

Why?

“If you wish to make an apple pie from scratch, you must first invent the universe.” – Carl Sagan

I have decided to have a crazy project wherein I’ll write an application in Common Lisp and only Common Lisp. That is to say, no other libraries. I have allowed myself to use extensions provided by the the implementation SBCL2 so luckily I won’t need to write my own socket and threading extensions.

This is a crazy and stupid idea. But the point of the project is to give me a place to play around with things I don’t normally deal with and in a language that I like to play with.

Test Driving a Testing Library

Where to start?

Common Lisp has no built in testing library, but it does have assert3. If you have assert you can write a testing library. The problem is writing the first test. I puzzled it over a little and decided I’d need a function which would take an expression to evaluate (the test) and would return some data structure which would indicate the results of the test. Given that here is the first test:

1
(assert (assoc :failure (test::collect-test-results (assert nil))))

So this is asserting that the return value of collect-test-results when applied to (assert nil) will be an alist4 which will have a cons cell whose car is :failure.

This test directly implies the following test:

1
(assert (not (assoc :failure (test::collect-test-results (assert t)))))

That is to say: if the expression does not raise an exception there will not be such an element in the returned alist.

After implementing a macro which lets those test pass I wrote some more tests to round out what I thought would be a useful implmentation of this base function of the library. I now had these tests to bootstrap my library.

1
2
3
4
5
6
7
(assert (assoc :failure (test::collect-test-results (assert nil))))
(assert (not (assoc :failure (test::collect-test-results (assert t)))))
(assert (equal (assoc :value (test::collect-test-results 'foo)) '(:value . foo)))
(assert (assoc :duration (test::collect-test-results 'foo)))
(assert (assoc :start (test::collect-test-results 'foo)))
(assert (assoc :end (test::collect-test-results 'foo)))
(format t "~A...PASSED~&" 'test::collect-test-results)

With this I felt that I had enough testing to make me feel confident in my little implementation. It wasn’t perfect - but good enough for me to now use this function to test other parts of my library.

How to write a test

With collect-test-results I had a way to writing and running individual simple tests. But it wasn’t a very convenient thing to use. But what it let me do is now write tests for deftest which would let me define tests. I started by writing the sort of test I wanted to write:

1
2
3
(deftest a-simple-failing-test
    "This is a very simple test which fails"
  (assert (= 5 (+ 2 2))))

Through a few tests, written using collect-test-results I determined that deftest would intern a symbol with the same name as the first argument of the deftest, bind its function property to a function which when called would, by calling collect-test-results evaluate the body of the deftest. These symbols were put into a list which could be retrieved from the library. Furthermore, defining a test with the same name as an existing test does not create a duplicate test.

It might be clearest to just show you how these tests (and an extracted helper function) ended up:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
(defmacro assert-no-failure (&body assertion)
  (let ((failure (gensym "fail")))
    `(let ((,failure (assoc :failure (test::collect-test-results
                                       (assert ,@assertion)))))
       (assert (not ,failure) () (format nil "~A" ,failure)))))

(deftest a-simple-failing-test
    "This is a very simple test which fails"
  (assert (= 5 (+ 2 2))))

(let ((test-list (test::test-list)))
  (assert-no-failure (equal test-list '(a-simple-failing-test)))
  (assert-no-failure (fboundp (car test-list)))
  (assert-no-failure (assoc :failure (funcall (car test-list))))
  (assert-no-failure (string= "This is a very simple test which fails"
                              (documentation (car test-list) 'function)))
  (assert-no-failure (equal (assoc :test-name (funcall (car test-list)))
                            '(:test-name . test-test::a-simple-failing-test))))

(deftest a-simple-failing-test
    "This is a very simple test which fails"
  (assert (= 5 (+ 2 2))))

(assert-no-failure (= (length (test::test-list)) 1))

(deftest a-simple-passing-test
    "This is a very simple test which passes"
  (assert (= 4 (+ 2 2))))

(assert-no-failure (= (length (test::test-list)) 2))

(format t "~A...PASSED~&" 'test:deftest)

Running tests

Now that we can define tests and evaluate them all that is left is to have a convenient way to run the defined tests. Three quick tests on the output of run-all-tests were proof enough for me (the tests that the call to run-all-tests would run were the ones defined above, one passing and one failing) that it would execute each test, report which ones failed and a count of passes and fails to *standard-output*.:

1
2
3
4
5
6
7
(let ((*standard-output* (make-string-output-stream)))
  (run-all-tests)
  (let ((output (get-output-stream-string *standard-output*)))
    (assert-no-failure (search "A-SIMPLE-FAILING-TEST...FAILED." output))
    (assert-no-failure (search "PASSED: 1" output))
    (assert-no-failure (search "FAILED: 1" output))))
(format t "~A...PASSED~&" 'test:run-all-tests)

Recap

At this point my testing library has two main entry points: deftest and run-all-tests. To create them, I first used assert to test drive the creation on a lower-level function collect-test-results, which I then used to test drive deftest, which I then used to test drive run-all-tests.

Next Steps and Thoughts

Now that I have this testing library I can use it to test drive the rest of the application I will write. I’m sure along the way I’ll be extending this library as I find new requirements for it. I’ll probably also be writing some assertion library to make the tests more expressive.

The resulting tests5 and code6 are in my GitHub repository for this project: yakshave7.


Clojure Project ‘Reloaded’ Pattern Gotcha

| Comments

Abstract

Ensure that user.clj does not contain dependencies (even transitive) upon code that needs to be compiled. This file is loaded well before Leiningen is started enough to compile files.

Problem Description

In my latest learning project with Clojure I decided to try Stuart Sierra’s Reloaded project pattern1. I liked the idea of this project pattern because it promised to make the REPL driven development on a web application smoother. Things were going smoothly as I worked on simple dummy pages for my little application. However when I connected the data file parsing code with its custom exception to the application I started getting compilation and class not found errors related to the custom exception. The reason for this is a rather simple one - but was difficult for me to find information on or figure out.

First an aside about custom exceptions. It seems that in the Clojure community that custom exceptions are avoided2. Either one of the built-in Java exceptions, ex-info3 or Slingshot4 is used instead. However it had been my favored approach to create a domain-specific exception for my application’s needed, so I stumbled forward and learned how to do it. It was relatively simple by using the :gen-class option of ns and the :aot feature of Leiningen. And it worked well… until I connected the code using the exception with the web application that was implemented in the reloaded pattern.

A big part of the reloaded pattern is the use of functions in user.clj to start and stop the system. This file is loaded by Clojure whenever it is started5 so it is perfect for functionality wanted in a REPL. This file is kept in a directory which is only included in the class path when the dev profile is used (the repl and compile tasks use the dev profile by default).

Everything is fine until the code in user.clj depends upon (even transitively) code which must be compiled (such as custom exceptions). Then we hit a annoying chicken-and-egg problem6 wherein Leiningen when trying to compile (or launch the REPL) naturally starts Clojure, which in turn loads user.clj which in turn depends upon code that needs to be compiled. The error that is reported says that the compiled class cannot be found.

The Confusion

This error led me to first think that my custom exception was not written properly and thus wasn’t being compiled, then I thought it was a problem of the :aot feature in Leiningen and interaction with the dev profile. But the problem was more fundamental. It was just my sort of luck that kept me from finding the answer until I spent hours debugging and researching. Now it is easy to find several reports of this problem7. It is not a Leiningen problem, not a Clojure problem, not a reloaded pattern problem, but an annoyingly unfortunate interaction between them.

The Workaround

Luckily, once the problem was identified, there is a relatively easy workaround. I took the parts of user.clj which depended upon the custom exception and moved those to a new file reloaded.clj which is then loaded when the REPL starts by using the :repl-options configuration in project.clj. :repl-options as a :init configuration which can contain an expression which is evaluated when the REPL is starting. I set it to (load "reloaded").


  1. http://thinkrelevance.com/blog/2013/06/04/clojure-workflow-reloaded

  2. http://tinyurl.com/o5kn5av

  3. https://clojuredocs.org/clojure.core/ex-info

  4. https://github.com/scgilardi/slingshot/blob/master/README.md

  5. http://dev.solita.fi/2014/03/18/pimp-my-repl.html

  6. https://en.wikipedia.org/wiki/Chicken_or_the_egg

  7. https://github.com/technomancy/leiningen/issues/1245, https://github.com/technomancy/leiningen/issues/1477, https://github.com/technomancy/leiningen/issues/1764, https://github.com/technomancy/leiningen/issues/1787

Mocking Class Constructor in Python With Mockito

| Comments

In the current code I’m working on we once and a while want to mock the constructor of a class. It is only really needed because we have a few classes who sadly do heavy-lifting in their constructors.

The common wisdom on the team was “you can’t do that”, but it bugged me and I eventually googled the right things and found out how to do it. The moment I did it myself I realized that it was obvious. Let me explain.

In [Python Mockito][https://code.google.com/p/mockito-python/] the standard form of stubbing is done with the when function, operating upon an object:

1
when(obj).method(arg1, arg2).thenReturn(5)

This states that when obj.method is called with arguments arg1 and arg2 then return 5. (There are other things to do besides thenReturn but for purposes of this discussion that is enough).

What about if you want to mock a constructor? The naïve approach is to try:

1
when(Klass).__init__(arg1, arg2).thenReturn(fakeKlassInstance)

But that doesn’t work. It will return an error equivalent to “NoneType does not have an attribute thenReturn”.

Making it work is pretty simple. Let’s say that Klass is defined in a module called klass. Then we can do the following:

1
2
import klass
when(klass).Klass(arg1, arg2).thenReturn(fakeKlassInstance)

It works because a module is an object on which the classes are methods! It was so obvious when I saw it work. The clues were right in from of my face, calling the constructor of a class is as simple as using the class name as if it were a function. That’s because it is! I’d like to blame too many years of Java & C# where “importing” is more about telling the linker where to find things than about creating objects that can be manipulated.

So to sum up: a class is a method on a module which returns an instance of that class. When you import a module you are creating a variable of that name bound to an object which represents that module.


Here is a test file which can be used to play with this idea. Note it uses the fact that the name of the current modules is bound to a variable called __name__ and that sys.modules is a hash of all modules.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import sys
import mockito

class Foo(object):
    def __init__(self):
        self.x = 5

    def method(self):
        return 10


f = Foo()
print f.method()
mockito.when(f).method().thenReturn('blah')
print f.method()

# This will not work and throw an error.
# print Foo()
# mockito.when(Foo).__init__(mockito.any()).thenReturn('blah')
# print Foo()

print Foo()
mockito.when(sys.modules[__name__]).Foo().thenReturn('blah')
print Foo()

The Cocktail Pattern Language

| Comments

Abstract

The idea of a “Pattern Language” is well known and well received in the Software community. Since the work of the Gang of Four1 it has helped in the communication of solutions and the discovery of new ones Cocktails have a pattern language which is well recognized by professionals but not by consumers. In this post I hope to make the Cocktail Pattern Language visible and useful to cocktail consumers and amateur bartenders.

What is a cocktail?

To begin with a “cocktail” is defined, classically, as the mixture of a “spirit”, sugar, water, bitters. This itself is less of a recipe for a specific drink as it is a pattern for all possible cocktails. While the modern concept of a cocktail has expanded from this origin it is still a good starting place for this discussion, and a fundamental example of cocktail patterns.

What is a pattern?

The elements of this language are entities called patterns. Each pattern describes a problem that occurs over and over again in our environment, and then describes the core of the solution to that problem, in such a way that you can use this solution a million times over, without ever doing it the same way twice. – Christopher Alexander2

Basically by “pattern” I mean a name for a particular way of doing something, a solution to a problem. A pattern does not dictate the only way to do something but shows the “shape” of the solution. The specifics of the situation will always cause variations.

Examples of Patterns

The easiest way to describe what cocktail patterns are is to give examples.

The Manhattan:

The recipe for a Manhattan is 2 parts Rye (or Bourbon), 1 part Sweet Vermouth and Angostura bitters. The recipe contains a main spirit: Rye, bitters: Angostura, and sweet: Vermouth (which also adds more kick and bit more bitter).

The simplest variant is The Rob Roy, replace the Rye with Scotch. Next simplest are the Dry and Perfect variants: Dry instead of Sweet Vermouth, or equal parts of two respectively.

A more differing variant is The Toronto: 2 oz. Rye, .25 oz Fernet Branca, .25 tsp sugar, Angostura bitters. While on the surface it doesn’t sounds like the same drink it is if you break it down. The main spirit is still Rye. The bitter & extra kick is added by the Fernet and Angostura while the sweet is provided directly by sugar.

Thus the pattern of a Manhattan is a whiskey paired with bitters and sweet.

The Martini

One cocktail which is (in)famous for its variants is the Martini. The pattern of a Martini is simply Gin (or Vodka) and Vermouth. Martinis can be Sweet, Perfect or Dry. The amount of vermouth can vary depending on the taste of the drinker. Different garnishes can be used, additional ingredients can be added as desired.

One variant is The Bronx. It is a Perfect Gin Martini with the addition of Orange Juice: 6 parts Gin, 3 parts Sweet Vermouth, 2 part Dry Vermouth and 3 parts Orange Juice.

Another variant is The Vesper Martini which is essentially a Dry Gin Martini: 3 oz. Gin, 1 oz Vodka, .5 oz Lillet Blanc3. It replaces the Vermouth with Lillet (similar to Vermouth in that it is a fortified wine with herbal ingredients).

One last variant is The Martinez which is basically a Sweet Martini: 2 oz Gin, .75 oz Sweet Vermouth, .25 oz Maraschino Liqueur and Angostura bitters. Here the Sweet Vermouth is augmented with Maraschino and a bit of bitters is added.

The Sour

A final pattern I’ll mention is the sour. Drinks in this pattern are The Whiskey sour, the Gimlet, the Daiquiri. The pattern here is a spirit along with a good amount of citrus juice (Lime often) and some sugar.

Why it is useful

The usefulness of speaking of patterns is to have a common terminology for discussing the situations designers already see over and over.4

Patterns in cocktails can be very useful to the bartender because it helps them choose the next drink for the patron. The patron may, as I do, say “I like Manhattans” or “I’d like something like a Daiquiri” and the bartender can rattle off a series of variants upon that pattern, or even invent their own.

Also the patterns overlap. For instance a Manhattan and a Sweet Martini have the same basic pattern: 2 spirit to 1 Sweet Vermouth. So a person who likes Manhattans may slide into Sweet Martinis and thus explore a whole new pattern of cocktails.

Thus the patterns of cocktails, as in Architecture and Programming, allow one to have a language to talk about the problem and possible solutions to it and to find new areas of discovery.


  1. Gamma, Helm, Johnson, and Vlissides. Design Patterns. Reading, MA: Addison-Wesley, 1995. Print.

  2. Alexander, Christopher. Pattern Language. New York: Oxford UP, 1977. Print.

  3. Due to recipe changes the current Lillet Blanc is sweeter and less bitter than previous versions. A better ingredient would be Cocchi Americano.

  4. “Cocktail.” Wikipedia. Wikimedia Foundation, 29 Oct. 2014. Web. 01 Nov. 2014. http://en.wikipedia.org/wiki/Cocktail.

To Estimating Bugs or Not: The Definitive Answer

| Comments

I was recently re-reading the XP books and in Extreme Programming Installed1 I came upon a section where the authors say that bugs should be estimated and planned into iterations like other stories. I disagreed with that idea, thinking about how ‘opinion had changed’ on that topic since the book was written and that ‘that’s not how I was taught to do it’.

Then I wondered why I thought that, just who had taught me that bugs should not be estimated. At first I assumed it was Jim Shore from The Art of Agile2, but a quick look in the book3 shows that he says to estimate bug stories. That led me to do some looking around the Internet4 and discuss this issue with my colleagues at Cyrus Innovation5.

I know believe I have the definitive answer to the question of whether or not to estimate bugs.

(First a clarification: I am not talking about defects found during an iteration in, or caused by, stories being worked on during that iteration. That just means that story is not done. Don’t take credit for it and create a bug card. Just accept that the story is not done.)

And now for that definitive answer:

It depends.

Some teams might find it useful to give the Customer the ability to prioritize bugs along with other work. By estimating the bugs the Customer has all the data they need to make their trade-offs. That being said: estimating bugs can be very difficult since there is often more than the usual share of unknown unknowns; thus the estimate will be less reliable than normal.

Some teams might find it useful to estimate bugs so that planning an iteration is easier. If a team knows it can do 14 points of work, then 14 points of work can be taken off the top of the backlog, maybe they are all bugs, or some bugs or no bugs; doesn’t matter - it is 14 points. If bugs are not estimated then maybe the team can do some bugs and how many more points? shrug.

Some teams might find that estimating bugs allows the number of bugs to be hidden among the work being done. They want to make sure that bugs are always visible, so they do not estimate want to make sure that bugs always detract from their velocity. Estimating bugs makes them a bit more normal and thus less visible.

So ultimately, as with any such question, the answer depends upon the needs and desires of the team. Do what works for you, and periodically question why and even try a different way.

(Drink Pairing: I paired the writing of this post with a simple Daiquiri6.)


and strain.

  1. http://www.amazon.com/Extreme-Programming-Installed-Ron-Jeffries/dp/0201708426/

  2. http://www.jamesshore.com/Agile-Book/

  3. My copy contains the note: “To Mark - Here’s to sucking less! Jim Shore”

  4. Specifically the World Wide Web section of the Internet.

  5. http://www.cyrusinnovation.com/

  6. 1.5oz Rum, .75oz Lime Juice, .25oz Simple Syrup. Shake over ice

What I Have (Re)-learned From SICP

| Comments

After about two years of slowly working through Structure and Interpretation of Computer Programs (SICP)1 I finally completed it. I didn’t do every exercise but I did many of them2.

The History

I first worked through SICP back in 1989 as part of my class at Worcester Polytechnic Institute (where I received my BSCS in 1992). It is a book that I remember with awe. I remember being, along with most of the class, mystified by this dumb language Scheme. It was so unlike anything we were used to. I was familiar with BASIC and Pascal and some very basic Bourne Shell scripting. Scheme was alien. Most of us thought it crazy. But then, somewhere about half-way through the class it clicked, suddenly I got it. Scheme, and Lisp by association, was amazing. The REPL development, the flexibility, the lack and regularity of syntax gave it great power. And then… then… we started on the chapter about the Meta-circular Evaluator3; writing an evaluator of Scheme in Scheme. It was so simple, so clear4.

This was a Freshman class, and the rest of my time at WPI I played around with Lisp, sometimes doing assignments in it, playing with my Emacs initialization files, that sort of thing. Never got serious. And then I joined the work force in 1990 with a summer job doing C/Motif work at a startup. And then after college a C job connecting their Windows app to a particular printer for graphs, and then a C/Motif job on a news ticker for a stock market application. Oh and then I learned5 object-oriented programming with C++… I forgot the lessons I learned in SICP.

The Return

I went back to SICP expecting to be reminded of a few things. What I found was that I was taught things I never remember being taught. Things which I so wish I had grokked at the time. Things which I obviously never understood and then forgot.

A few of the things I learned way back when and then forgot were:

  • Judge a programming language by the means of abstraction and the means of composition.
  • The power/utility of REPL development.
  • Lazy streams to deal with infinities are not scary.
  • Functional Programming.
  • Object-Oriented Programming.
  • The Problem of State.

The Reaction

This is a Freshman level textbook, and all of this was taught as early as the mid-eighties. Looking back I feel like I was caught up in a great forgetting. There are things we (as Software Engineers6) knew and then forgot, or chose to forget/overlook.

Now I see people going back to old papers/books and re-learning/discovering what we already knew but forgot/ignored. It is like a wider version of Greenspun’s tenth rule7. We had something and then had to put it aside because it didn’t work in our “reality”, but now we come back and “discover” it all over again.

OMG Garbage Collection8 OMG interactive language shells (aka REPL) OMG dynamic languages OMG functional programming OMG OO is about message passing.

What happened, were we asleep?

It would be one thing if we acted like these are in fact old ideas that are just now realizing are good/possible - but we act like they are new. Reality has caught up to where the 1960’s thought was possible9.

The Back to the Future

One last thing I (re)learned: The fun of learning and working through problems. And that leads to what is yet to come.

I’m going to start looking at the old texts of our practice. The ancients knew things that we have forgotten. I will see what I can learn from them. I will strive to avoid Argument from Antiquity however, that is always a danger with this sort of thing.

I can only see so far because I stand upon the shoulders of Giants10.


  1. http://mitpress.mit.edu/sicp/

  2. https://github.com/verdammelt/sicp

  3. http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-26.html#%_sec_4.1

  4. It was in this class I created the joke idea of ‘God code’. The stereotypical 3 line Lisp code, first line defines function, second like is a null check, third line recurses. And shit got done.

  5. learned

  6. Software Engineer, Programmer, Coder, Hacker whatever you want to call us/ourselves.

  7. “Any sufficiently complicated C or FORTRAN program contains an ad hoc, informally-specified, bug-ridden, slow implementation of half of Common Lisp.”

  8. http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-33.html#%_sec_5.3

  9. http://www-formal.stanford.edu/jmc/recursive.pdf

  10. with apologies to Newton.

Thoughts About the Domain Model

| Comments

The CHECKS Pattern Language paper(Cunningham 1994) has some good ideas about what they call “Information Integrity”, ensuring that inputs are parsed/validated/handled well. But I also found that it made some good statements about the domain model in general. I’m going to write about a few of these quotes here.

Your domain model must express the “logic” of the business in its richest and often illogical detail. Every clause of every statement should be motivated by some business fact of life.

A program will always have an unfortunate amount of code in it, but an important chunk of it is the domain model. That part that is the reason for the application. Not the code that does the jQuery jiggery-pokery, not the mallocs and frees. When the business rules change this is where the change will be made. Keep it clean and uncluttered with non-domain details. If there are details in it which do not correspond to the domain logic then there will be confusion when talking about the domain with the experts. If the code doesn’t express the domain the way the domain experts talk about it, or it is incomplete, then there will be confusion again.

In your domain models you are chartered to express business logic with no more complexity than originally conceived or currently expressed.

Domain logic can be complicated to begin with. It doesn’t help that you are not an expert in the domain of (e.g) Etruscan Snoods, but you need to write a program to work with them. You talk with the experts and translate their expertise into a program. Don’t make it more complicated than it already is. Keep it simple and to the point so it is easy to talk about it with the domain experts. If it is not easy to discuss what it does with the domain experts then adding new features or finding/fixing problems with it will be more difficult.

A person reaches through a program’s interface to manipulate the domain model.

This is an important thought - the user thinks and talks about the domain with a certain language, pattern and style; make sure your program talks their language. If the program’s interface doesn’t match the user’s language then the user will have trouble using it, or using it correctly. Data should be labeled with the right words, operations with the correct terms, and permissible inputs and output formats must match expected conventions.

In closing the paper discusses good patterns for dealing with inputs and the domain model, but I think that it is the above quotes really that really stand out as good things to think about.

Serving Coffee With Express

| Comments

A few weeks ago I was playing around with a new stack: Node-Express-Angular all in CoffeeScript1. I found it quite easy to have the Express server compile my CoffeeScript files and then return the JavaScript to the browser. I then found myself last week in a position at work where I wanted a little test page to hang the Angular directives I was working on so I quickly used the same trick.

I’m not saying this trick is bullet-proof, or even a necessarily good idea for production. But it seems like a good thing for testing and perhaps for getting a project off the ground with some prototyping. It also serves as a small example of how to write an Express Middleware2.

With that caveat I will present you with the code and explanation of it3.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
express = require 'express'
coffee = require 'coffee-script'
fs = require 'fs'

app = express()

app.configure ->
  app.set 'port', process.env.PORT ? 3000

app.use express.logger()

app.use '/client', (request, response, next) ->
  coffeeFile = path.join __dirname, "../client", request.path
  file = fs.read coffeeFile, "utf-8", (err, data) ->
    return next() if err?
    response
      .contentType('text/javascript')
      .send coffee.compile data

app.listen app.get('port'), ->
  console.log 'listening on port %d', app.get('port')

The part that concerns us are lines 12-18. This section is telling Express that if a request comes in with a path starting with /client that we will want to do some special processing on it.

  • Line 13 determines the path to the CoffeeScript file (which is in the ../client directory relative to our current directory). Of note here is that request.path does not contain the /client part of the path and __dirname is the directory of the currently executing file.

  • Line 14 sets up the reading of this CoffeeScript file. It is important to specify the encoding otherwise the Coffeescript compile will throw an error.

  • If there is an error reading the file (line 15), such as the file not existing, then we tell express to run whatever is the next rule (eventually if no other rules work Express will send a 404 for us).

  • If we can read the file then we use CoffeeScript to compile that file (line 18) and send that data back as the response (lines 16-18). (Of note here is that we set the content type to be text/javascript (line 17) to make sure that the browser does the right thing (it doesn’t appear necessary with Chrome at least, but probably best to do it.)).

Congratulations, we’ve just written an Express Middleware!


  1. It is my current opinion that CoffeeScript is better than writing directly in JavaScript. It saves the developer from making some very basic stupid mistakes with JavaScript and also removes some of the syntatic noise.

  2. [](http://expressjs.com/4x/api.html#middleware)

  3. The toy app bootstrapping kit I mentioned at the top of this post is in my expressular-kit. The code here is not a direct copy of the code there in app/server/app.coffee.

Only One Way of Doing Things…

| Comments

When there is only one way of doing things, it is easier to
modify and reuse code. When code is reused, programs are easier
to change and most importantly, shrink. When a program shrinks
its construction and maintenance requires fewer people which
allows for more opportunities for reuse to be found. Consistency
leads to reuse, reuse leads to conciseness, conciseness leads to
understanding.

Programming as Experience: The Inspiration of Self (1995)

Resuse

I like the meaning of ‘reuse’ in this quote. This is not the ‘reuse’ promised by early OO proponents. They promised1: that one would be able to create objects which would be reused from one project to another. This is the reuse which means that code is reused in a project. This is the reuse which I believe to be attainable.

It is like a inward-spiral: the more reuse of code the fewer ways to do a thing there will be which leads to only one way.

The sentence about fewer people is a bit odd - but I feel it is does make sense. The fewer people on the team the more likey there will be only one way to do things which means there is by definition more reuse.

Consistency

Perhaps more important than reuse though is consistency. If code is consistent I have found it to be easier to reason about, because reasonable assumptions can be made when reading it. Being able to make reasonable assumptions, and have those borne out, is very important to me when reading code.

Conciseness and Understanding

And it follows that with reuse and consistency one will get consiceness. But does that necessarily lead to underderstanding? That is something I feel is right, but I have seen some concise code which is hard to understand.


References:

  • “Programming as Experience: The Inspiration of Self”, 1995, Smith, Randall B and Ungar, David

  1. Or perhaps that is not what they said, but what we heard.