pl patterns

Code Must Be Fluid

Mon, 13 Dec 2010 12:09:00 -0500

The first law of software – and life – is change.

It doesn’t matter how easy a programming language or tool makes things. If your code isn’t fluid – if your data and algorithms can’t flow between components – you will always run into problems.

Do You Remember the Time...?

Fri, 19 Nov 2010 10:02:13 -0500

Do you remember the time we went for ice cream?

We tend to believe that when we remember something, it’s because that something actually happened in the past. When I remember walking to get ice cream this afternoon, I believe I actually did get ice cream this afternoon. But the reason I believe that, is because of memory. In other words, we use memory to justify the validity of memory – a circular argument if I’ve ever seen one.

For example, I want to remember the web address “plpatterns.com”. When I get home from work, I want to be able to type that address into my browser. To try to prove that I remember the address correctly, I write it down on a piece of paper and put it in my pocket. So now, when I get home, I type in the address that I remember: plpatterns.com. But wait, is my memory accurate? Is the address that I remember actually the one I saw earlier in the day? To find out, I can compare the address I remember against the one I wrote down on the piece of paper in my pocket. Look, they match! Therefore, my memory is accurate. When I remember something, I can be reasonably confident that it did indeed happen. …Right?

But wait… How did I know that what I wrote down in my pocket is what I actually saw earlier that day? Well, because I remember writing it down when I saw it. And I’m certain that I didn’t change what I wrote on the paper or switch papers – because I don’t remember doing that. …So I am essentially justifying my memory with other memories. There is really no way to know that what I remember ever actually happened. What I remember matches with what my friend remembers? Great! But that still doesn’t prove that what we remember actually happened, because any justification we use is based on other memories accurately representing what happened.

What are the implications of all this? Essentially, these things occasionally pop into my mind, like thoughts, but for some reason that I can’t prove, I compulsively believe that they represent things that I did before, saw before, heard before, said before. In fact, the entire concept of time is based on this belief that I can remember, with some amount of accuracy, what the Universe looked like before. And it’s all based on these things that pop into my mind – which we call “memories” – that I have absolutely no justification for.

Every time you remember something, you’re recalling it now. Right now. Every time you imagine what will happen in the future, you’re imagining it now. Right now. Nothing ever happens at any time other than now.

In the movie Blade Runner, we’re provoked to question who we are based on the idea that our memories might not be ours. But it’s much more drastic than that. You don’t need a futuristic city with androids running around. You just have to look, right now, and see for yourself through your own first-hand direct experience – that any time other than now is a made-up mental construct. A figment of your imagination.

Notes from Rich Hickey's Keynote at ClojureConj

Mon, 25 Oct 2010 11:38:00 -0400

I greatly appreciate being around inspiring people. This weekend I was fortunate enough to be around many inspiring people at ClojureConj, the kind of people who question their reality, not just their programming tools.

When was the last time you spent an entire hour thinking about a problem?
- a day
- a month

Practice to be good at something.

Problem Solving
1. What is the problem?
- out loud
- written
2. Understand the problem
- what do you know?
- what don’t you know?
- are there related problems?
3. Be discerning
- problems in your own solution?
- what tradeoffs?
- read in and around your space
- explore multiple options to say what tradeoffs were

Focus - “On the hammock, no one knows you’re not sleeping.”

Use waking mind time to feed work to background mind.

Loading
- Mind can juggle 7+/-2 things.
- When more, write it down.
- Go over in different order. Load in different combinations.
- Have no-input receptive time.

Wait
- at least overnight, sober
- sometimes months
- work on more than one thing
- not interleaved within a day, but over the course of time
- switch when stuck

Try it
- Get feedback
- Evidence may show that assumptions were wrong

You will be wrong
- You will think of better ideas
- Input facts change
- You’ll make mistakes
- It’s okay

When you read something, and you know that’s bogus, that’s positive!

“The beautiful thing about ideas is that they don’t have feelings.”
- If you have implemented a bad idea, you start to not like it.
- Detachment is natural.
- Why would you want to keep around a bad idea?
- Get rid of it. It’s not a child. It doesn’t have feelings.

Update 2010-10-27: Stumbled on Rich Hickey’s Clojure Bookshelf full of books about advanced programming topics, plus a hammock.

"Studying history helps you predict the future by teaching you which things are old enough to be..."

Wed, 22 Sep 2010 14:54:43 -0400

“Studying history helps you predict the future by teaching you which things are old enough to be permanent.”

- Paul Graham

Every time you use CSS, you're doing Aspect-Oriented Programming

Mon, 29 Mar 2010 13:35:00 -0400

Each AOP term and its HTML/CSS counterpart…

AOP	HTML/CSS	explanation
join point	every HTML element	places you could possibly apply behavior
pointcut	CSS selector (e.g. `#nav span.highlight`)	expression that specifies which places to apply behavior
advice	CSS declarations (e.g. `color: blue; margin: 1em;`)	what behavior to apply
aspect	logical grouping of CSS statements (selectors + declarations), sometimes separated into its own .css file	module that groups the combination of what behaviors to apply and where to apply them that logically has to do with the same thing/feature (i.e. have the same concern)

Once you start spending a lot of time writing HTML and CSS, you start to see patterns. Groups of CSS rules that you re-use all the time. CSS classes can be used as functions.

Instead of saying:

<div style="clear: both">

… you can define a clear class …

.clear {
  clear: both;
}

… and then say …

<div class="clear">

At first, this might not seem like it saves a lot, but depending on your site, the patterns may be bigger. For example, when I was working with Chap Ambrose, I discovered he used a class called float_left all over. I immediately assumed it applied the single rule “float: left”, so I began using it too. However, I got frustrated when I realized the “float_left” class applied two rules:

.float_left {
  float: left;
  margin-right: 1em;
}

Eventually, though, by spending more time writing HTML/CSS, it became obvious to me that a lot of the time, when I want to float something, I also don’t want the things next to it bumping up against it. I want there to be a margin. And so the pattern (or function) is born.

So What about Aspect-Oriented Programming?

A group of CSS rules is essentially a function. (They even use the same curly-brace and semicolon syntax.) But with CSS, you actually don’t have to explicitly call a function to use it. Where you define the CSS rules (or function), you can use a selector instead of a class name which injects the behavior where you want it. The advantage is that you never have to explicitly reference the CSS rules where they’re used – i.e. you never have to explicitly call the function.

When you write the following CSS statement, you’re injecting the behavior of the rules into your entire site, without touching the code that’s already there.

form h1 {
  font-size: 15px;
  color: blue;
}

Suddenly, all h1 tags inside forms have this behavior, even though none of them reference this “function”.

Aspect-oriented programming is the most misunderstood programming paradigm. But fundamentally, the reason it exists is the same reason CSS exists – to better separate concerns in your code.

To die without your love knowing how you really feel...

Sat, 30 Jan 2010 17:31:06 -0500

…must be the worst fate imaginable.

Question: How do you communicate how you really feel? How do you let your love know that she is loved? Really loved. You know you love her… but does she really get it? I struggled with these questions for a long time. Being naturally bad at communicating due to [programmers’ Asperger’s](http://www.joelonsoftware.com/items/2004/08/20.html) didn’t help. Last year, though, I stumbled on [_The Five Love Languages_](http://www.amazon.com/gp/product/1881273105?ie=UTF8&tag=plpatterns-20&linkCode=as2&camp=1789&creative=390957&creativeASIN=1881273105). The premise of the book is that there are concrete ways to communicate love and appreciation for another person (all forms of it, not necessarily romantic). The author gives many examples and shows a pattern among them. The ways to communicate love can be grouped into 5 categories, each embodying a “love language”.

According to Chapman, the 5 languages are:

Words of Affirmation
Quality Time
Gifts
Acts of Service
Physical Touch

Think of a time in your life when you really felt loved. That one time… Was it when someone told you were great at something you thought you were lousy at? Was it when you hung out together at the bus station because the bus was late, and ended up talking for hours? Was it the time years ago that you received a gift, that maybe wasn’t expensive, but meant so much to you that you cherish it to this day? Was it the time someone trudged out in the pouring rain for you, so you didn’t have to? Or was it the time someone embraced you, at just the right moment?

We naturally try to give what we think is valuable. But the more I learn about other people, the more I learn that different people are different. They value different things. They think differently. They perceive the world differently.

If you really care about someone, give them what they want, not what you wish others would give you.

This is quite possibly the only book I have ever read that I think would be valuable for any person on the planet. Maybe how to communicate love is obvious to some people, but it was never obvious to me.

It's hard to change a little. It's much easier to change a lot.

Wed, 30 Dec 2009 08:57:04 -0500

When you try to change a little, your old mindset still has its old values and attachments, and you inevitably slide back into your old groove. But when you change enough to create a new mindset, you can free yourself from your old way of looking at things and create a _new_ groove.

Homer Simpson’s ass groove comes to mind. Moving over a few inches would be painful at best. Moving across the couch to a new cushion would be like starting fresh. The mind and habits work the same way.

This has happened to me a number of times.

Waking Up Earlier

For years I tried to wake up about 30 minutes earlier than my regular routine. It would work for a while, but then I’d inevitably start waking up later and later until I reached my regular schedule. However, when I got a new job that required me to wake up 2 hours earlier, sure it was tough at first, like adjusting to jet lag, but it became my new routine. And I’ve had no problems consistently waking up 2 hours earlier than my old routine.

CVS/Subversion -> Distributed Version Control

I used to use CVS for version control at work. For a small project, a co-worker and I tried using Mercurial. On the surface, Mercurial is very similar to CVS, and it was very easy as a CVS user to just pick up Mercurial and get started using it. It ended up being nice, but we perceived it as CVS + local commits and a few other “neat” features. Nothing game-changing. Months go by and I decide to give distributed version control another shot. This time I tried git. Git is so different from CVS that I was forced to literally stop what I was doing and learn git. This seemed bad, but it forced me to change how I thought about version control. I used to think of version control as something that was akin to writing in stone because it was expensive and could never be changed. However, now I see everything as patches, and patches are cheap, can be applied, rolled back, and re-ordered. A completely different mindset. Now I’m hooked on distributed version control and couldn’t live without it.

Imperative Programming -> Functional Programming

People I have known who tried learning functional programming using a language that supports functional features but allows falling back on imperative loops and statements… they end up never really getting it because they inevitably fall back on their old imperative ways. When I was taught functional programming at Carnegie Mellon, it was mandated that we use Standard ML without any assignment statements (i.e. no references). I was completely lost for the first couple weeks, but after a certain point, it clicked – and from then on, I have been thinking functionally ever since.

So if you want to change how you think about something, in the long-run it’s hard to change a little; it’s much easier to change a lot.

Robot Visions

Sun, 13 Dec 2009 23:27:38 -0500

When I was a kid, barely old enough to read, I saw this book Robot Visions, by Isaac Asimov in the bookstores. I poured over Ralph McQuarrie’s illustrations (long before I ever knew who he was) and wanted to read it more than anything else.

Now, almost 20 years later, I discovered it in my uncle’s library – the original hardcover edition – and I’m finally reading it. And loving it!

It is truly an exciting time. Many predictions seemingly of the distant future are likely just around the corner. Others, we must still dream about.

It is my guess that the 21st century may see a society in which one-third of the population will be engaged in entertaining the other two-thirds.
And there are bound to be new forms of entertainment that one can now foresee only dimly. Three-dimensional TV is easy to forecast. And space may become a new arena for activity. In near-zero gravity, for example, the manipulation of balls may produce far more complicated forms of tennis or soccer. Ballet and even social dancing may become incredibly startling and require a new kind of coordination that’s delightful to watch, as it will be as easy to move up and down as it is to move forward and backward or left and right.

We’re already beginning to see this “work as play” phenomenon. People in my generation expect work to be fun. When it’s not, they quit and do something else (or “bum around” as long as their funds allow it). In fact, in my recent letter of resignation, I even stated that I was leaving “to pursue fun in the web startup world”. I considered writing something more “professional”, but decided against it because I wanted to be honest.

Experts in learning-theory like Kathy Sierra are realizing that you can apply game-design to just about anything, making even the most tedious tasks fun. After seeing this, there’s no reason to ever go back to the old way!

For those who see patterns and the robotic nature of decision-making (like science-fiction writers), the future may not be as clear as the past, but it is just as obvious.

The Purpose

Tue, 01 Dec 2009 20:18:00 -0500

I want to make software that people use. I’m tired of making stuff that gets used by one person once a month.

The purpose of software ultimately boils down to one of these things: * To help people work * To entertain people * To teach people * To keep people safe * _To help people pursue happiness_ Software can help people. If it doesn’t, it hasn’t fulfilled its purpose. I always tell people at work that my job as a developer is to remove myself from the process – by replacing myself with software. If I do that, I’ve created an asset for the company. If I don’t, I’ve created a liability.

Related: The Question
Photo by jedzer

The Question

Sun, 15 Nov 2009 17:28:00 -0500

A skilled sculptor can form any shape. A skilled programmer can make any program. The only question is, what?

I think this rings true with anyone who has spent 10 years in the field. After a certain point, you start to realize, there’s nothing you couldn’t program. Sure, there are challenges. How do you get it to be fast enough? How do you allow it to scale big enough? But at the end of the day, after having faced challenging problems in the past and eventually overcoming them, you begin to realize that it’s no longer a matter of whether you can make it, but more… what’s worth making in the first place?

Paul Graham said, “Once you know what to make, it’s mere effort to make it, and most decent hackers are capable of that.”

“Every block of stone has a statue inside it and it is the task of the sculptor to discover it.” – Michelangelo

No matter what your craft, after a certain amount of practice you become a master craftsman. But the tradition of creating a masterpiece to cross the line from apprentice to master has faded away.

Deep down, we who love the craft still want this. And we wonder, what is worth making?

The result of our work can either be that awful thing in the park no one wants to look at, but has to, or David.

Related: The Purpose
Photo by jasontheaker.

Conrad Barski of lisperati.com gives a taste of his new (not yet...

Sat, 14 Nov 2009 22:39:00 -0500

Conrad Barski of lisperati.com gives a taste of his new (not yet released) book, Land of Lisp, at Philly Lambda. On Lisp + Game Programming!

Update 11/19/2010: Land of Lisp is out! Get it here.

How to Convert a Local Branch in Git to a Remote SVN Branch

Thu, 05 Nov 2009 18:24:00 -0500

This is a little more obscure git-svn recipe I derived today. Thought I would share it.

Basically, I was prototyping a new feature on a local branch in git. Later, I decided I wanted to push that local branch into an svn branch so that my svn comrades could see it. So I started with a local branch following svn trunk with purely fast-forward commits. And the following did the trick.

Create the svn branch.

svn cp <url-to-svn-repo>/trunk <url-to-svn-repo>/branches/final-remote-name
git fetch        # Sync w/ remote svn repo.
git branch -r    # This should list final-remote-name.

Make a new local branch with your feature that follows the new svn branch.

git checkout local-feature-branch   # This is the local branch where your prototype feature is committed.
git checkout -b final-local-name    # This makes the local branch derived from your local feature branch that will eventually become the branch that tracks the remote svn branch.
git svn info     # This will say you are following trunk.
git rebase remotes/final-remote-name

Verify.

git log         # All of your feature commits should be on top, followed by the commit that created the svn branch, followed by trunk commits.
git svn info    # This should now say you are following the svn branch, final-remote-name.

If everything looks good, push all your feature commits to the remote svn branch.

git svn dcommit

You can optionally delete the local feature branch that is following trunk, so you don’t use it by accident.

git branch -D local-feature-branch

Basically all it amounts to is a rebase, with some svn trickery.

So again, all together now…

svn cp <url-to-svn-repo>/trunk <url-to-svn-repo>/branches/final-remote-name
git fetch
git checkout local-feature-branch
git checkout -b final-local-name
git rebase remotes/final-remote-name
git log         # Check your commits.
git svn info    # Check you are following the svn branch.
git svn dcommit
git branch -D local-feature-branch    # Delete old local branch.

I hope someone finds this useful.

Blub by Convention (In Defense of Arc)

Tue, 03 Nov 2009 08:25:00 -0500

The entire [Arc language](http://paulgraham.com/arc.html) is just a few Scheme macros. …Or so the criticism says. I can’t use Common Lisp. `mapcar`, `lambda`, `destructuring-bind`, etc. These are things I use all the time, yet they have some of the longest, most unnecessary names. Scheme is the Java of Lisps. `define`, `begin`, `list-ref`, etc. It was seemingly designed to be as descriptive as possible, and in doing so, also became as verbose as possible. Yes, it’s true that I can redefine all those things. But at that point I’ve created Arc. So if you see the pain of using mapcar and list-ref, then in a nutshell, you see the need for Arc. Period. In the same way that Perl has functional programming features, but the community and conventions don’t use it that way, which means the libraries aren’t designed for functional code, hindering your use of it, so too are Common Lisp and Scheme hindering. The conventions hinder the use of its full potential. Lisp is potential. Untapped potential. Arc is an attempt at tapping it. [

](http://www.flickr.com/photos/19722425@N02/3890967883/) The [blub paradox](http://paulgraham.com/avg.html) implies that once you truly get the features of Lisp – first-class continuations, condition-signals and restarts, macros, serialization of code to syntactically valid code – all the imitation features like function objects, exceptions, Ruby’s catch/throw, the C-preprocessor, and serialization to XML are… disappointing at best. Atrociously unusable at worst. This is why Lisp is more powerful than non-Lisps. But Arc is better than other Lisps because Lisp by definition is flexible. And flexibility is a double-edged sword. You can define anything to be anything – both in a good way and a bad way. Arc was specifically designed to pull out common patterns and be as concise as possible. If it’s true that Arc is just a bunch of macros, then these macros that I would have had to define myself in Common Lisp or Scheme are part of the core language or conventions of Arc. So instead of only me knowing about those macros, all Arc programmers know about them. Code that does not follow a convention is more difficult to integrate with code that does, so much so, that the fact that libraries exist using a convention is a huge incentive to use the same convention. Additionally, if I write code that does not follow the convention, people who maintain my code inevitably re-write it in their own image. It happens slowly over time perhaps, but inevitably. Every one of those names (mapcar, lambda, list-ref), and dozens more in the core language and standard libraries, is a kludge. But if I redefined them, the first thing someone else touching my code would do is look at it, say “wtf!”, and delete my redefinitions and change everything back to the canonical use. In Arc, on the other hand, instead of my code degrading to the conventions of Common Lisp over time as I move on and others take over my code, it holds the high caliber of the conventions of Arc. However, if you actually succeed at changing all those kludge names in Common Lisp, you will have improved the language by an order of magnitude. And when you improve something by an order of magnitude, you haven’t made something better, you’ve made something new. (Hence, Arc is genuinely new.) Basically, non-Lisps are blub compared to Lisp because they limit what you can abstract. However, once you have a dialect of Lisp, there are so few visible barriers to abstraction. Instead, non-Arc Lisps are blub compared to Arc because the conventions adopted by the community – and lack of a ability to [change](http://plpatterns.com/post/37655893/the-prototype-production-knob) those conventions – create barriers to flexibility, removing one of the very features that makes Lisp so great. Put another way, non-Arc Lisps are blub by convention. The macros that make Arc Arc are a big deal because they are an attempt to change the convention. What I am getting at is: 1. Many languages could be better than they are if they used different conventions. 2. It’s damn-near impossible to go against the conventions. 3. Conventions are difficult to change, more of a way of thinking of the community. 4. It’s worthwhile to push good conventions into the core language/libraries, and if you do that, you’re essentially making something new. This has little to do with Arc, except that Arc is an example where someone (Paul Graham) tried to do #4 because of 1 through 3.

Photo by rachell.

Thanks to Kyle Burton for helping develop the idea for this post.

Alternative to XML Validation

Sun, 18 Oct 2009 15:44:00 -0400

The desire to validate the structure of a document has come up a number of times recently. Say you have a public service where one of its operations takes in a complicated tree-structured document. You want a way to:

use a programming-language-agnostic data format for your document;
formally specify the expected structure of the doc;
validate that input to calls to your service actually follow the structure;
and hopefully, allow clients to do this validation themselves, w/o hitting your service.

A well-known language-agnostic way of doing all this is with XML as your document format, an XML schema as your specification of the expected structure, and XML validation as the publicly known algorithm for validating.

Having done some type-theory, I would much rather say that my data format is a data structure in a programming language, the spec of the structure is a type declaration, and validation is type-checking.

So I’ve wondered, is there a solution to my problem 1 through 4 – without using XML?

A few well-known programming-language-agnostic data-formats are: s-expressions, JSON, YAML. I have found Kwalify for YAML, but not much else.

This is a shame because people who believe they might ever need 2 through 4, choose XML for 1 (pl-agnostic data format) simply because they don’t know of any alternatives. This sucks because if all you are doing is 1, then you’ve made the worst choice for the job.

XML sucks to read as a human b/c there is so much extra noise. It gets to the point where the majority of your effort spent reading XML is filtering. It also sucks to use in programming b/c the API is terrible. XML doesn’t map perfectly to the data-structures in most languages, even Java, its biggest fan.

So again, if all you’re using it for is 1 – a programming-language-agnostic data format – XML is one of the worst choices. Yet, the fact that XML dominates in 2 through 4, it remains the default.

The unspoken truth about managing geeks

Thu, 10 Sep 2009 10:59:00 -0400

The unspoken truth about managing geeks:

Articulates the mindset of many developers.

It’s not about being right for the sake of being right but being right for the sake of saving a lot of time, effort, money and credibility. IT is a team sport, so being right or wrong impacts other members of the group in non-trivial ways.

Truly insightful.

IT pros would prefer to make a good decision than to get credit for it. What will make them seek credit is the danger that a member of the group or management who is dangerous to the process might receive the credit for the work instead.

Thank you for stating this. It’s the truth.

Unlike in many industries, the fight in most IT groups is in how to get things done, not how to avoid work. IT pros will self-organize, disrupt and subvert in the name of accomplishing work.

… in fact, getting things done faster is the reason I started programming in the first place.

We can all learn from articles like this.

Sending an IM via Gtalk in Clojure

Sat, 22 Aug 2009 23:39:00 -0400

Email has its place, but when it comes to short notifications – of the status of a job, for example – IMs work great.

If you think of your software as your co-worker – someone you work with who helps you do your job – all kinds of functionality just make sense. Would you rather your co-worker emailed you or IMed you? Then the software should do that.

This code snippet sends an IM using Smack 3.1.0, a Jabber client library (Apache 2.0 license).
Download the Smack jar.
Browse Smack source.

Note: you must invite the username to chat and confirm in Gmail before messages will get sent.

user> (def conf (org.jivesoftware.smack.ConnectionConfiguration. "talk.google.com" 5222 "gmail.com"))
#'user/conf
user> (def con (org.jivesoftware.smack.XMPPConnection. conf))
#'user/con
user> (.connect con)
nil
user> (org.jivesoftware.smack.SASLAuthentication/supportSASLMechanism "PLAIN" 0)
nil
user> (.login con "my.username@gmail.com" "mypassword" "resource")
nil
user> (.isAuthenticated con)  ;; check that we are authenticated
true
user> (def chat (.createChat (.getChatManager con) "send.to.username@gmail.com" nil))  ;; this nil is the listener -- put something here to receive IMs!
#'user/chat
user> ;; Invite to chat in Gmail -- sending messages won't work w/o doing this!
nil
user> (.sendMessage chat "it works!")
nil
user> (.disconnect con)
nil

Update: I created a project that uses this along with log4j, letting you pull a logger out of nowhere and send out status IMs.

If you would be ...

Mon, 10 Aug 2009 00:56:48 -0400

Here’s something I’ve noticed recently: if you would be Xed, be Xable.

A few concrete examples…

If you would be taught, be teachable.
If you would be understood, be understandable.
If your software would be used, make it be usable.

And last but not least, the quote of Ovid that inspired it all: If you would be loved, be loveable.

Git Config

Thu, 09 Jul 2009 14:43:00 -0400

Here’s the .gitconfig file I’ve been using. The aliases let you type “git ci” and execute “git commit -v” for example. And color is essential. Going back to svn is like going back to black & white TV.

[user]
        email = you@blah.com
        name = Your Name
[color]
        ui = auto
        diff = auto
        status = auto
        interactive = auto
[alias]
        st = status
        au = add -u
        pt = add --patch
        ci = commit -v
        cia = commit -av
        br = branch
        co = checkout
        df = diff
        dfc = diff --cached
        dfw = diff --color-words
        lg = log -p
        spull = !git-svn fetch && git-svn rebase --local
        spush = !git-svn dcommit

Setting Up Clojure

Mon, 22 Jun 2009 11:37:00 -0400

Notes I made back in April for setting up Clojure on my MacBook. Kyle is planning a workshop on this soon.

# get Clojure and clojure-contrib library
cd ~/projects
svn checkout http://clojure.googlecode.com/svn/trunk/ clojure
svn checkout http://clojure-contrib.googlecode.com/svn/trunk/ clojure-contrib

# build Clojure
cd clojure
ant

# make a clojure executable on your path
echo 'java -cp ~/projects/clojure/clojure.jar clojure.lang.Repl' > ~/local/bin/clojure
chmod a+x ~/local/bin/clojure

# setup env
cd ~/projects
git clone git://github.com/mdelaurentis/env.git
cd env
git submodule update --init
cd
ln -s projects/ src
echo '(load-file (expand-file-name "~/projects/env/emacs/dot-emacs.el"))' >> .emacs

# slime and swank
cd projects/
git clone git://github.com/jochu/swank-clojure.git
git clone git://git.boinkor.net/slime.git

Knowledge Representation

Sat, 16 May 2009 14:50:00 -0400

When I write a program, what I’m essentially doing is writing down my best understanding of how to solve a problem or accomplish a task. My best understanding.

For the sake of this discussion, let’s say the problem I’m trying to solve is how to best peel an orange for eating.

An interesting thing happens, though, when I spend hours and hours talking about the problem, thinking about it, drawing diagrams of it on the whiteboard, relating it to other problems I’m familiar with, and coding it: I begin to understand the solution better. But not only that, I begin to understand the problem and its entire domain better.

With this deeper understanding of the domain, comes more precise terminology. For example, in my study of orange peeling, I discover that when there is a breach in the skin, the juice squirts out when I put pressure on it. But when the skin is perfectly intact, the juice doesn’t squirt out; it kind of oozes out from all over. So I might call these spots on the orange “squirt points” and “ooze points” from now on. But as soon as someone new to the domain of orange peeling hears the phrase “squirt point”, that person probably won’t know what I mean.

To me, the same statement using the term “squirt point” is much clearer than the one that says “the points on the orange where juice tends to squirt out when pressure is applied to the skin, usually implying there is a breach in the skin”, even though they technically mean the same thing. Someone unfamiliar with the term, on the other hand, will probably think the exact opposite.

Yes, the term “squirt point” is a reference to this longer, more descriptive definition, and it can just about always be replaced by its definition without changing the meaning of a sentence. But the fact that I’m using the term has more information. It means that when I say “squirt point” over here, and “squirt point” over there, I’m referring to the same exact thing. What if over here I use the full definition inline, but over there, I use the full definition except I say “when pressure is applied to the orange” instead of “when pressure is applied to the skin”. Is that the same thing? Is it a mistake? Did the person who wrote it (whether that be another physical person, or me years ago) actually mean to write “skin”? On top of that, even if the full definition is used exactly alike in both places, it takes significantly more work for the human mind’s limited pattern matching ability to recognize that similarity, compared with the short term.

We have to be careful though. It’s not as simple as making a rule that says: everyone should always use the term.

What if there are thousands of terms specific to this domain? Does everyone seriously have to learn them all before writing a single thing about orange peeling? What if there is a similar concept that overlaps 90%? Should a new term be coined? Or should the original term be modified? Say I want to talk about the points on the orange that juice squirts out when pressure is applied after the skin is already peeled. It’s essentially the same as “squirt points”, where the orange’s skin is not present. If I know the term “squirt point”, then I will be tempted to use that term, slightly modified. But if I overload that term, essentially creating a new definition for it, I’ve just changed the meaning of every other thing that refers to it, whether that be pieces of writing, learning material, documentation, code references, project plans, issues, or even other people’s mental references to the term.

In the worst case, I could have just broken something, making what made sense before no longer make sense. Regardless, making the definition of a term more general implicitly makes everything that refers to it more complex, because in the more general version of “squirt point”, the fact that pressure is being apply to the skin is no longer contained within the term. So when relevant (which itself may not always be clear), things referring to “squirt point” now must also say whether the skin is present or not.

For those that haven’t already been doing this, I encourage you to imagine what happens with this discussion when you replace the word “term” with “function”, because this problem constantly arises when more than one person are involved in a software project. Because developers are literally writing down their understanding of the solution to the problem in code, the resulting software can only be as good as the developers’ understanding of the problem domain.

This means that if you are a developer, you should do everything in your power to understand everything about your problem domain. Not just the specific task at hand, but the big picture where it all fits in. Not just how to fulfill the requirements given to you, but what requirements were probably missed completely because the people writing the requirements have less understanding of certain domains related to software.

But this also means that if you are running a company, and you are not a developer, you should do everything in your power to get the developers to understand everything about your problem domain – because the software that they produce, can only be as good as their understanding. If you simply give them requirements, they will do their best to interpret those requirements in the context of everything they understand (just like anyone else). That isn’t enough. There are 53.2 million ways to skin a cat. You won’t get the way that you want unless in addition to saying what you want, you also say why you want it. This is essential for a developer. Because every developer is a designer, whether they like it or not. They are constantly making decisions that affect the business as a whole. If developers don’t understand why end-users want a feature, for example, it’s likely they will misjudge the importance of the feature and make an unacceptable trade-off in the design process.