code


22
Oct 10

freelance

House made out of $50 bills

I'm not sure what this has to do with Freelancing, thanks Google!

I’ve been hard at work making sure that Faveroo keeps humming along, pushing out new features here and there and making sure everyone is happy. The growth we’ve seen has been steady and we are continuing to push forward. Work has been a little hectic lately, if anyone ever tells you that growing a product and a brand is easy, you just punch them right in the face, I don’t care that it’s your Grandma, do what I say, I’m a blogger. Anyways this blog post isn’t about my 9-5 it’s about my 6-10.

I do a lot of cool side projects, some of them like Prosper are just for fun, they scratch an itch I have and I think I might be able to use them later. Some never see the light of day, they lose momentum or turn into something that I can’t figure out how to make any money or help anyone with so they just languish on my hard drive. Lately I’ve been trying to break into the freelancing stuff, I thought, how hard could this be, I have years of experience, I’m willing to work for a reasonable price, I write high quality code really fast, and I tend to think that I’m a fairly nice person to work with. Well its been an uphill battle so far, but I want to share my thoughts with you.

Online freelance boards just suck. They do, I hate you, I hate them, hate is really the only emotion I can feel about these boards. 90% of the posts are for ridiculously ill-defined or impossible jobs, 99.999% of the replies are someone in some third world country willing to write the new facebook for a shiny new nickel, and there is no way to get the point across to anyone that you get what you pay for. I’ve yet to find any useful paying work from these sites.

Craigslist is a mixed bag so far. When I started on this journey I got some help from a friend who basically just spammed me with every blog post they could find on the subject of freelance consulting. A nice thread on Hacker News, here’s a Two part series by Ryan Waggoner on freelancing. One of the pieces of advice was to use Craigslist, so I tried that, there is a ridiculous volume of stuff in the Computer Gigs section, and since you aren’t constrained by geography you can apply to a huge amount of them. I tried this for a few weeks but after sending out tens of emails, most custom written specifically for the project and only receiving one reply, I decided to try another avenue. I’m not giving up on the Craigslist approach yet, if for no other reason then the absolute mass of postings there.

Friends of friends. Right now this is where I’ve seen my only success. I’m currently working on a project for a friend of a friend and so far things are looking great. I’m enjoying the work, sweet lady PHP with my favorite unframework, Flourish, and I’m making great progress. It’s been a good project to work on so far, the client has been great to work with, and the code has been flowing. I’m sure there’s a downside to to this course, friends of friends will want you to do extra work for them for free or change things up as a solid, but so far so good.

Future plans. This blog post is part of it, but basically some self-promotion is in order. I’m going to be putting together an online portfolio of stuff I’ve done, Prosper is a nice large code base for someone to look at to see the quality of my PHP code. I realized I just need to get my name out there as an option, the current project I got was because I happened to tell my friend I’m trying to start consulting on the side, bam, first paying gig. I’m going to keep fighting the good fight on Craigslist, maybe come up with a more efficient system for submitting my name into consideration for postings.

If you need a good PHP programmer drop me a line in the comments or send an email to ihumanable@gmail.com and maybe I can write some awesome code for you.


31
Aug 10

2 months

Faveroo Logo

that's a pretty sweet logo

On June 3rd I typed the following into my Terminal.

mkdir faveroo
cd faveroo
git init

On August 15th I typed the following into my Terminal.

cd ~/src/faveroo
php deploy.php production

Then I watched and held my breath as my carefully crafted deployment script worked its way through 2 months of code and pushed them across the line. Then I fired up my browser and went to http://faveroo.com and waited for the now familiar homepage to show up… I’m sure it took less than a second to load, but it seemed like an eternity, finally it was up. I worked for the next few hours exercising the application through all its various operations, squishing little bugs here and there that popped up from being in a different environment. Two months of development, and finally it was live, and it actually worked. A few hours later we started hooking up people with sweet deals and putting money in the bank, mission accomplished.

Faveroo.com is my first project at my new job at 614 Media Group. It was a skunkworks project up through the end of July, so I couldn’t come to this blog and talk about it. I did all of the coding for Faveroo and my colleague Jeff Guciardo did all the design work to make it look so pretty (it’s probably the prettiest thing I’ve ever had the opportunity to create). The basic premise of the website is that our team of dedicated sales people go and find great local deals, then we throw them up on Faveroo.com, and then we help people save some cash. When you buy a Faveroo you save some money, the business makes money, we make money, and 3% of the sale automatically goes to charity, it’s win-win-win-win. But I’m neither marketing nor sales, so I will stick with what I know and what I knows is tech, so let’s talk about that for a minute.

Faveroo is a PHP website that includes the public frontend, a private backend, and a series of maintenance scripts that make sure everything works like clockwork. When I was starting up the Faveroo project I was given carte blanche as to how to build it. All of our other web properties use the classic LAMP stack, so to keep operations fairly sane and because I deeply love PHP, I decided to build out Faveroo on a classic LAMP stack as well. The code is Object Oriented, nearly MVC, PHP 5.2 code. I looked around, had been for a long time, at various PHP Web Frameworks. I had just come off of working with rails on a side project and so I knew the joy and frustration of work with a framework.

As you may be aware, I’m crazy in love with Flourish and decided that I would use it as a major component. I have been a fan of Flourish for a while now, probably over a year, but this was the first big application I was going to use it on, and really the first large scale from scratch application I have ever written. Now don’t get me wrong, I’m no rookie to this slinging code stuff, I’ve maintained huge legacy applications, built middle-ware up from nothing, and even rewritten large applications to the point that almost all of the original code has been replaced. But this would be the first time that if I didn’t like something in my code, it was because I was the stupid jack-ass that made such a boneheaded decision. Well, not the first time, but the first time I couldn’t easily blame someone else ;)

I want to say that the decision to go with Flourish is probably what made the rapid turn around time possible. It’s a wonderful library that helps you do things right but doesn’t force you to do anything you don’t need. The thing that amazed me as I used it is I started off only wanting to pull bits and pieces, maybe some fCryptography here and a little fMessaging there, but as I got familiar (and boy howdy did I get familiar) with the docs, I just found more and more amazing functionality and a beautifully coherent system. Flourish was clearly written to be used, and by the end of the project I found I was using almost every class. It’s clearly a tool written for real world use from real world experience.

Flourish and jQuery are really the 2 big external dependencies for Faveroo, the rest of the code was written by me. I found this minimal system worked very well for me. I wrote a router in about 100 lines of PHP code, it’s nothing earth shattering but I think it has a few novel ideas. I’ve since built a new version of this router that is shorter and has less complex code paths. At some point in the future I may try to make a more generic version of this router and release it open source. All of the model classes are fairly straightforward using the excellent fActiveRecord as a base.

I spent about a week spinning up my minimalist framework, but it paid off big. I knew how the system worked every step of the way, and more importantly, I could alter it in minor ways to achieve dramatic results. All of this is possible with established frameworks, but here I got away without having to climb up a learning curve. This gave me more time to understand the problem domain and to learn how to best use Flourish.

With this experience under my belt I’m looking forward to continuing to learn, and hopefully to contribute back to, Flourish and PHP development in general. This project has shown me that in 2 months I can go from nothing to cash hitting the bank account. I feel reinvigorated to make cool things that add value to people’s lives and reassured of my abilities as a programmer. After a long period feeling burned out and wasted, I remember why I love programming, and why I love creating, and why this is the only thing I can ever see myself doing.


31
Mar 10

micro-optimization

nero fiddling as rome burns

Yea, I know it's on fire, but check it, I almost got Freebird down pat.

As all good developers should know, one of the cardinal sins of software development is premature optimization. Premature optimization is bad for a whole host of reasons. But there is another set of optimizations that are in the same realm of bad, micro-optimizations.

I recall learning at some point that in C and C++ it is more efficient to use the pre-increment operator rather than the post-increment operator. Why is this the case, well it’s because of the minor difference in behavior between the following two snippets.

  int source = 10;
  int destination = 0;

  destination = ++source;

  printf("Destination: %d", destination);  //Prints "Destination: 11"

Compare with this snippet

  int source = 10;
  int destination = 0;

  destination = source++;

  printf("Destination: %d", destination); //Prints "Destination: 10"

WHA!? This is actually exactly what we would expect, pre-increment increments the value BEFORE assignment while post-increment increments the value AFTER assignment. What does this all mean, well basically that if you use post-increment you are executing more instructions, because the compiler has to keep the old value around to return to the assignment. That means that unless you are assigning the value and require the particular behavior that post-increment gives you, you can generate faster code by using the pre-increment operator (this may be handled by compiler optimizations these days).

All of the for-loops that you’ve written for(int i = 0; i < something; i++) are identical to and SLOWER than for(int i = 0; i < something; ++i). NOOOOO!!!!! Don't worry though, because this is a micro-optimization, its something to not care about, because in reality that one or two extra machine instructions isn't your bottleneck. Micro-optimizations are all those tricks that make code faster that in the vast majority of cases (although not all cases) don't really amount to any actual noticeable performance gain. A new processor can do something in the magnitude of 100,000 MIPS (Millions of Instructions Per Second). Every second it does 100,000,000,000 Instructions, that is 100 billion instructions. every. single. second. Changing from post- to pre- increment saves 1 or 2 instructions, so for every time that gets executed you have saved a 100th of a nanosecond.

Micro-optimizations are rarely worth the hassle, and, as with premature optimization, the solution is to benchmark and trace where your actual bottlenecks are and go about solving those. It doesn't matter if you're screaming through your increments saving a whole nanosecond if your crappy no index having table is taking a whole minute to read because you are doing a table-scan.

But wait, there's more. Micro-optimization, like everything in programming, can be directly applied to life in general. I work with a person who will spend 5 minutes discussing how to save 30 seconds, this is another incarnation of the micro-optimization. It's that shortcut you take home that actually takes longer, or some everyday voodoo that is draining your time without paying you back, or that client that provides you with 2% of your income but eats up 40% of your effort. Micro-optimizations abound all around us, in the little picture they seem ok, but in the big picture they are nonsense. Take a fresh look at the things and obligations around you and examine them for micro-optimizations, see if the things you do make sense in the big picture.


11
Feb 10

password usability

A friend pointed me to an interesting article on A List Apart. If you don’t want to read through the whole thing it basically says that a lot of password resets are caused by people remembering their passwords correctly but mistyping them. The concerns that once made masking passwords with asterisks are now being eclipsed by the usability problems this design has introduced. The post goes on to describe two potential alternatives, a toggle to show the password in plaintext (similar to the WiFi configuration screen in Windows) or to show the last character typed while masking the rest (similar to the iPhone or Android password inputs).

Both of these options are interesting and I personally would like to see either one gain greater acceptance, although with the rise of password managers built into Operating Systems and Web Browsers it seems less and less necessary. The problem with both of these techniques is discussed in the article, that changing the functionality of the password input undermines the user’s confidence in your site’s security. This is why I think that changing the nature of password inputs is dubious at best until it gains widespread adoption, maybe if Google were to implement them or some other web giant. Until that day I think a fine alternative would be Mattt Thompson’s Chroma-Hash.

Chroma-Hash augments a password input with extra information. Something that is easy to remember and easy to notice when its wrong, a color swatch called the Chroma-Hash. Let’s take a look at how it works.

chroma hash example

The password (conveniently enough 'password') generates the colorful hash to the right.

The passwords match because the colors match, when entering your password you are informed of mistypings immediately by the hash being incorrect. Let’s take a look at what happens if we carelessly fat-finger the confirmation typing “passworf” instead of “password” like it should be.

chroma hash with mismatch

One little letter completely changes the Chroma-Hash, immediate feedback

Small changes in the password generate big changes in the Chroma-Hash. The human brain is one of the best pattern matching engines in the world, Chroma-Hash leverages this fact. Very small changes in a sites design or color scheme are detectable, that’s why people make a big deal when a site they commonly visit changes things, even slightly. This makes Chroma-Hash ideal for serving as a “password proxy.” Others can see the Chroma-Hash and gain no information about your password and yet it instantly gives you a wealth of feedback about whether or not you have entered the correct password.

Take a look at Chroma-Hash, fork it on GitHub, implement it on your website. You get the advantage of recognizable feedback without needing to change the fundamental way in which the password input works.


9
Feb 10

time

clock

Finally was able to get the clock to show me its good side, dirty girl

Don’t worry this won’t be a rant about mortality or getting things done or any of the philosophy that has been dominating this blog as of late. This is back to basics, a discussion about software and a particularly tricky aspect of it, time. Not time as in, scheduling and managing time, but something far more fundamental representing time. It is an insidiously tricky problem and one that can be quite difficult to wrap your head around.

The problem comes from how we think about time as people living normal lives. “I’ll meet you at 3 o’clock” is a rather dull and completely normal type of phrase to say to someone. As two normal people living normal lives, this simple phrase “3 o’clock” is plenty to convey when they should meet. This is because there exists a great deal of unspoken context between the two parties, if we are meeting for a business meeting I clearly mean 3:00pm not 3:00am. If we both work in the same building I probably mean relative to the our shared timezone, 3:00pm EST not 3:00pm GMT. There is a world of shared unspoken context that makes human-human time discussions easy and natural.

Computers are really stupid though, they need everything spelled out. If you were trying to store time you might take a naive approach at first and just store the string “3:00″ maybe if you are really thinking it out you would store “3:00pm EST.” This method soon starts showing its weaknesses as its hard to compare times, or perform operations on them. How many hours are between 2:00am EST and 5:30pm CST? There is a nasty problem to try to solve unless you have some sort of way to represent times in the abstract.

In steps a number of formats to represent time. There is the venerable Unix Timestamp which is the number of seconds from Jan. 1, 1970 as of my current writing it stands at 1265738039, but feel free to check for yourself. Then there are numerous proprietary formats like Microsoft’s, Oracle’s, etc. These all allow you to represent an exact moment of time in a portable abstract way with no dependence on the cavalcade of context us fleshy humans share.

Well problem solved, just bust out your favorite abstract representation and you are done. Not so fast, there are many other considerations to take into account when dealing with time. There are of course the tricky problems of Daylight’s Saving Time, leap years, and the like. Imagine you are trying to add an event to a calendar system everyday at 5:00pm EST, you think you could just add it to today and then just add 24 hours and create a new event. DST hits your algorithm over the head at some point and everything is off an hour, oh no! Also now you have a ton of data to represent one basic fact, something happens everyday at 5:00pm EST. Its only one fact, you should need one record, not an infinite number of 5:00pm EST records. This hints at the next difficulty of time.

Humans think about repeatable events (sometimes with complex and insane rules) as commonplace and easy. This thing happens on the third Thursday of every month, unless of course Monday was a holiday and then it gets shifted to Friday. The problem with time and dates and repeating events is that human beings erected a ton of complex processing rules before they realized we were going to try and digitize them. These are difficult to represent and difficult to get right.

At first the task of representing arbitrary points and spans of time seems fairly straightforward, but it is a complex and nuanced task, like most things the devil is in the details. Before you go off half-cocked building up your own representation, take a look at some established formats, like Unix Timestamps, RFC5545, and ISO 8601.


1
Feb 10

open format

bank safe

We'll just lock your data up in here, don't worry we'll open it up later if you need it. This is what a closed format sounds like

Back in the days when a computer had 64k of RAM and high-capacity meant you had a double-sided floppy disc, there were these funny little things called binary file formats. We still have them today, they are the “pattern” that a program will write and read to and from disc to save and load a file into a program. Some are open, like image file formats, and some are closed, like Microsoft’s binary blob formats for Office. As the world has advanced and storage has become dirt cheap people started looking for an easier way, and whenever there is a problem that we don’t have a tool for yet, we reached for XML.

XML is actually not a bad fit for this problem domain, its a little on the ugly side, but that’s ok, very few people crack open a raw file to read it. The people that are cracking open files in a text editor to peer inside are probably tech-savvy enough to read a little XML. The big bonus of switching to XML, like ODF or DOCX, is that there are very mature XML parsers and writers for almost every programming language. That means that a determined programmer can grab a copy of your format spec, her favorite XML parser, and write a program that operates on your file format. This is the essence of that oh-so-marketing-speak word synergy.

Now I would love to take credit for this awesome idea, but if you’ve read The Art of Unix Programming you will recognize this as nothing more than an extension of the Rule of Composition. Now that you’ve read the Rule of Composition (and you should make the time to read the rest of the Art of Unix Programming, even if you never plan on programming anything for Unix, the lessons within are just in general great to know), you will recognize the inherent advantage of having parsable file formats. Now that I have cunningly converted you over to my way of thinking, what format should you use?

XML

XML (eXtensible Markup Language) is the old standby, it is reliable, standardized by the W3C, well-supported, and there are tons of tools around for playing with XML. XML is “human-readable” for those of you unfamiliar with it here is an example.

&lt;book&gt;
  &lt;title&gt;Example Book&lt;/title&gt;
  &lt;pages&gt;
    &lt;page&gt;
      &lt;![CDATA[
        ...page stuff here...
      ]]&gt;
    &lt;/page&gt;
    &lt;page&gt;
      ...you get the idea...
    &lt;/page&gt;
  &lt;/pages&gt;
&lt;/book&gt;    

Its a bit tag-heavy and that means a slightly large file size, this isn’t a huge concern since storage is so cheap, but you should be aware of it. XML has a neat feature called DTD (Document Type Definition), armed with this most parsers will be able to tell right away if a document is well formed. XML is big and clunky but a fine choice for many applications, especially if you need typing information.

YAML

YAML (YAML Ain’t Markup Language) is the format of choice for the ruby community. YAML is well supported by most mainstream programming languages, it is a more lightweight choice than XML. Here is the same thing as above in YAML.

book: Example Book
  pages: 
    - page: &gt;
      ...here goes my page data...
    - page: &gt;
      ...you get the idea....

YAML uses the structure of the text to indicate the structure of the data. Ending tags are dropped and indentation becomes more important. YAML looks simplistic at first but has a wide-array of functionality hiding below the simple hello world examples. References, hashes, arrays, and much more are possible with YAML. The specification allows you to make concise documents that contain an astounding amount of information.

JSON

JSON (JavaScript Object Notation) is a lightweight way to represent data structures. JSON excels by being incredibly simple to learn and use. There is native support for it in JavaScript which makes it ideal for use in AJAX (which would then technically by called AJAJ), and there are JSON parser available in most mainstream languages. Here is the example from above in JSON.

{title: &quot;Example Book&quot;, pages: [ page: &quot;...page stuff goes here...&quot;, page: &quot;...you get the idea...&quot; ] };

Just like in JavaScript everything in JSON is a Hash or Array. JSON is a simple typeless data recording system, perfect for dynamic languages. JSON is a proper subset of YAML 1.2 so most YAML parsers can also parse JSON. JSON’s incredibly lightweight nature lends itself for being used when sending data over a wire or when space is at a premium.

BSON

BSON (Binary JavaScript Object Notation) is a binary form of JSON. It is meant to be more space efficient than JSON but maintain the ease of parsing. It is described as “A General-Purpose Data Format” and was devised as the serialization medium for the MongoDB project. It is an interesting format to look at if space is at a premium and there are already parsers for C, C++, PHP, Python, and Ruby.


File formats no longer need to be gnarled, tangled messes. We have new standards that allow us to freely share data created in one program to be analyzed, manipulated, and turned into something new in another program. Being able to freely interoperate is the future of computing, it is the driving force behind web standardizations, micro formats, and open file formats. The next time you need to persist data to the file system, resist the urge to roll your own serialization scheme, and check out one of the technologies presented above. The world will thank you.


29
Jan 10

learn autoit

autoit

Bezels and shadows and reflections, oh my

If you use windows at work or at play this post is for you, macheads and linux people I’m sorry, this post probably won’t help you much. I have had the joy of doing documentation work for the last 2-3 months at work. Gnarly, ugly documentation that serves little purpose other than making someone feel happy that there are reams and reams of documentation. At some point, probably around the 5th document, I made the realization that out of 20 pages it was mostly boilerplate, with about 8 things peppered throughout that changed. I decided that it would be easiest to make a template document and then just do a find and replace on those eight symbols [[DOCNUM]] [[DOCNAME]] [[DOCTRANSACTION]] etc.

Productivity shot up, I could now stub out a document in a few minutes instead of the hour or so that it used to take to manually hunt through and change things. All was well and after a day or two of find / replacing I had stubbed out the 80 or so documents. Then came the meeting where it was decided that 2 new sections would be needed and that 8 sections could be removed as being redundant. This victory for common sense was also a giant headache, as I didn’t really look forward to restubbing 80 documents. There had to be an easier way, a better way, I remembered a screen driver tool I had some exposure to at a past engagement, AutoIt.

After reading through the documentation and goofing around with it for a while yesterday I now have a fully functional script that will automatically stub out all of the documentation with the click of a button. A task that used to be an error-prone, manually intensive process now requires no intervention. We can restub on demand now, so changing the template is no problem.

The Good

  • Saves a ton of time
  • Removes the human aspect from an existing process
  • Centralizes specific knowledge
  • Easy to write and test

The new script saves a ton of time, I can regenerate all documentation in about 10 minutes, so I click a button and go walk around the office bugging people. AutoIt simply takes a known working process and steps in to be the person driving it, I didn’t have to take time dreaming up a brand new workflow, I could focus on just getting it done. The script is now the system of record for the specific things that change from document to document, which is nice for trying to determine at a glance what makes an HCR1 different from a ARC6 command, without digging through 40 pages of documentation. AutoIt also utilizes a stripped down version of SciTE with auto-completion and built in support for compiling and running, which makes writing and testing the script a breeze.

The Bad

  • Ugly syntax (like VBScript and PHP had a bastard child)
  • Oddly organized documentation and variably helpful community
  • Inherently brittle scripts
  • Still slower than I’d like
  • Foreground processing

AutoIt has an ugly syntax (think VBScript), but it has all the pieces parts to make a nice script, functions and variables. The documentation takes a little getting used to, there is plenty in there, but it could be organized better. AutoIt depends on things like the window title and absolute paths, so it is inherently brittle, I doubt this script would run unaltered on someone else’s machine. This could just be me being a n00b at AutoIt but I followed the practices laid out in the tutorials and the documentation. The other bad part about AutoIt is that it drives your screen, it simulates you pressing buttons and mousing about, so the script is slow and you can’t interact with the machine while its running or you will probably mess everything up.

Alternatives

After proclaiming my victory over the documentation monster, I got some replies from colleagues asking why I didn’t just make a powershell or ruby program or java program or something. I could have cracked open OpenWriter or something and attempted to build some massive program that could create .docx files, but that would have taken a ton of time. The AutoIt solution was incredibly quick to produce, took about 2 hours of playing around with it. There were a bunch of side benefits that the alternatives wouldn’t have had. The template file is just a plain ordinary .docx file with all kinds of crazy formatting and images, instead of trying to figure out how to reproduce this in code, I can use Word to do the heavy lifting for me. This allows business users to change the template and we can rapidly restub and get back up and running.

Conclusion

You should go and learn AutoIt or AppleScript or whatever GUI driver program is available for your platform. It is not the tool for every job, but it’s perfect for some jobs. Being the person on your team that can take some boring, error-prone, laborious task and turn it into a turn-crank task is a great thing. You can save your team time, get back to doing actual work more quickly, and make a name for yourself as a problem solver.


26
Jan 10

when in rome

collisium

Trust me, you want to do what the Romans do, I mean... have you ever built a Collisium?

Ah the cliché of it all, “When in Rome.” Although it would be nice to have a post about being in or traveling to Rome, sadly this is not the case. Instead, this post is about following convention and how that can help you learn.

I’ve been getting into ruby as of late, after learning Smalltalk, Objective-C, and LISP (to varying degrees), ruby hits a nice sweet spot of stealing some of the best bits from each. I was recently approached by a friend who does primarily .Net programming about the best way to go about learning ruby. He had decided that, at least in the beginning, he should use the NetBeans IDE. This seems harmless enough, even logical for someone who spends their entire day in Visual Studio to want the comforting guidance of the IDE. It is also the exact wrong approach.

As he progressed past simple “Hello World” examples and onto his first rails project he found himself battling with the IDE. Odd error messages, the IDE struggling to provide auto-completion on the dynamic models, but most importantly a complete lack of resources. The ruby and rails world to a large degree lives and breathes on the command line, right now if you go to my home computer you will find 4 terminal windows arranged with a mysql shell, script/console, script/server, and one for git. If something goes wrong and I get a weird error, I do what all great programmers do, copy and paste that sucker into Google. I normally find somewhere around a bajillion hits with solutions, huzzah!

My friend on the other hand had trouble doing the simple things through the IDE, like installing gems. I’m certain the IDE was capable of it, and that someone better versed in it would be able to help him out, but the Google-scape was barren to his questioning. All I could say to answer his questions were, “well I’m not sure how NetBeans does it, but on the command line just type gem install [gem]” (Also I can speak in teletype, I just do a robot voice.)

Despite the difficulties, my friend clung to the belief that the IDE was the way to go for beginners. I finally realized the perfect analogy to drive home the point, I asked, “Would you ever advise someone new to .Net to learn it by using the command line tools?” It’s a perfectly valid question, I’m sure plenty of people who hang out in vim all day and don’t mind doing things like ./configure && make && sudo make install (thanks Jeremiah for pointing out my n00bishness) would feel much more at home on the command line.

I am not free of fault on this either, when I attempted to learn git for the first time, I used TortoiseGit. I was very comfortable with TortoiseSVN and thought it would ease the transition. It sure did, I was able to treat git exactly like svn, and completely miss the point! Once I moved to the command line (and watched some screencasts and read some articles) I felt much more at home with git, and even began to understand why I would want to use it over svn. I had stopped trying to make it something it isn’t and embraced the thing that it is.

The point here is that when you learn something new, it’s new, don’t bring along your technological baggage. If the community all rallies around some IDE (.Net, I’m looking at you) then for flying spaghetti monster’s sake, use that IDE. If they rally around the command line (ruby, I’m looking at you) then by the hammer of Thor, use the command line. If they rally around some weird virtual environment machine (smalltalk, I’m looking at you) then have fun and realize you are never going to be able to use that at work (just poking fun, I <3 smalltalk).

The point here is that learning something new is often times uncomfortable, you have to feel like a tourist for a while. When in Rome though, do as the Romans do. Embrace the methodologies, naming conventions, and tools that are the community standard. Give it a few weeks, if you still find yourself hating it, then maybe that particular technology isn’t for you, it’s ok, we can’t all love everything. Life is about trying new things and figuring out what makes you want to get out of bed in the morning, for some people it will be .Net, for some ruby, for some COBOL (just kidding, no one likes COBOL).

You never do yourself any favors by half-way learning something, because you will either hate it because it was poorly shoehorned into an inappropriate paradigm, or you will learn to love it. “That second thing doesn’t sound too bad” (I can sense your thoughts), and at first blush its not, until you want to start participating with the community by using others’ code and sharing your code. Then you will have to unlearn all the bad practices you’ve adopted and have a difficult transition into the community, attempting to erase months of muscle memory. Save yourself the difficult task of trying to unlearn something and simply embrace the technology in full to begin with. It’s a steeper curve, but the payout is the depth of understanding.


25
Jan 10

api

samsung microwave

oh creator of hot pockets, we praise thee!

I remember being a young lad preparing myself for university I was given a gift from my mother, “C++ for dummies.” The vote of confidence on my status as a “dummy” aside, I read the book with great interest. There was an analogy the author used to explain the idea of classes and what functions they should expose, I’m going to shamelessly steal it (paraphrasing as I don’t have the book with me).

Imagine your son comes up to you and says he wants to make some nachos. You tell him that its fine by you, just go cook them in the microwave, and there is nothing controversial about this statement. Microwaves are actually boxes full of high energy radiation being produced by cavity magnetrons or waveguides, to the end user, the microwave is just a magic warming box. It exposes a very simple interface, some buttons that allow you to enter the amount of time you want to cook something.

This is the essence of an API (Application Programming Interface), wrapping up something complex and possibly dangerous in something safe and easy to interact with. When building code that you intend other people to use someday, it is the part that is most important part, and the part that is easiest to overlook. The problem is that we are often too close to something and too concerned with our use case. If you want to design code for others to use, it requires significant time and effort, and even then you probably still won’t get it right.

Prosper is still undergoing active development, I’m currently agonizing over how I want to expose various execution modes. The solution, no matter what I pick, is trivial to implement, but the api is the most important part. A great api exposes a consistent concept, something that is easily grasped and allows the end user of the api to declare what they want to do without having to worry about how its going to get done. Since good programmers write good code and great programmers steal great code, I’ve modeled the api for prosper extensively off of jQuery. And why not, let’s take a look at two different APIs, the browser dom api and jquery.

  //Let's barber pole a list by coloring every other element blue
  var list = document.getElementById('the_list');
  var highlight = false;
  for(var i = 0; i &lt; list.children.length; i++) {
    if(highlight) {
      list.children[i].style['backgroundColor'] = '#FF0000';
    }
    highlight = !highlight;
  }

Fairly straightforward implementation, but it concerns itself heavily with the “how” of what its doing. Manually traversing to pick the elements it wants, eww.

//Same thing using jquery
$(&quot;ul#the_list li:odd&quot;).css(&quot;background-color&quot;, &quot;#FF0000&quot;);

jQuery is definitely magic, but this code is great because it let’s you focus on the “what” of what you are doing. How does jQuery go about selecting the right elements and all that? I don’t care, and the great thing is I don’t have to care, and if in the next version of jQuery they find a way to do it faster, I win without having to do anything.

Writing a great api is difficult, you have to divorce yourself from the concrete problem you are solving and look at it in the abstract. Put yourself into the shoes of someone trying to figure out how the api works, and then ask the questions they are going to ask.

  • Why do I need to build up this context thing and pass it in?
  • How come there isn’t a sensible default for these arguments?
  • What dumbass made this thing?

Answer those questions, and keep working at it, strive for elegance and consistency, because then it will be easy for people to learn and use. If your code is easy to learn and use, people are going to want to use it more, and they are going to want to tell their friends about it. Then you can get some lucrative ad campaigns with Nike because of the boffo library you write in FoxPro.

There is a more subtle lesson in all of this though. Any code you write is exposing an api to someone else. “But only I am ever going to use this code!” I hear the naysayers warming up their keyboards for the comments section. This may be true now, but the six-months-from-now-you is going to look back at the you-of-today and wonder what the hell he was thinking.

Get in the habit of making your code easy to use, and expose a nice api. This will endear you to your fellow programmers and help make maintenance easy. Strive to be that guy on the team that writes functions and classes people want to use. Make life easier for your fellow developers and even if they don’t return the favor, maybe they will take you out for a beer. People notice over time that your code is the best to work with, they internalize it, and they start to think of you as a great programmer. That’s a pretty great api to expose to the world.


11
Jan 10

grok

banging head

necessary part of grokking something

Computer nerds should be familiar with the term grok while the rest of the populace has no need for such a silly word. You may hear it down at your favorite nerdery, “I don’t quite grok this” or “Once I grokked it, I flew through the project.” What does this word mean though and where did it come from.

Grok for the non-nerd means, “to understand thoroughly and intuitively.” Although this is true it belies what it truly means to grok something. For that we need to realize the origin of this fantastic geek speak, this term is straight out of Robert A. Heinlein’s Stranger in a Strange Land. He defined it as follows

Grok means to understand so thoroughly that the observer becomes a part of the observed—to merge, blend, intermarry, lose identity in group experience. It means almost everything that we mean by religion, philosophy, and science—and it means as little to us (because of our Earthly assumptions) as color means to a blind man.

The great thing about grokking something is that it changes your world view, it fundamentally shifts the way that you see, perceive, and understand the world. The bad thing about grokking something is that it is incredibly difficult to get to that point. Let’s take a look at a fantastic chart I’ve whipped up to help us understand this better.

grok

the graph of grokitude

In this graph we have time and effort along the horizontal and understanding along the vertical. We can spend a great deal of time after “mastering” a subject before we get the epiphany and truly grok something. To really understand a subject on the level that a computer nerd would consider grokking it takes not only a full in-depth knowledge of the function of something, but an understanding of the design, an internalization of the principals, and a familiarity that borders on oneness.

This is the reward for hundreds or thousands of man-hours spent toiling in something, the day when the clouds part and you truly understand something, this has an amazing non-linear effect on your understanding and your productivity. Once you grok something, be it a framework or a library or a concept, your ability to use that and your productivity in it increase in a non-linear fashion.

Although it is important to have a wide breadth of knowledge we must remember the importance of having a few areas of incredible depths of knowledge. These areas will permeate everything else you do, so try to choose wisely. The subjects that you truly grok are the ones that will effect your big picture outlook.

Here are my suggestions for some fundamental things to learn, and learn to a point that it fundamentally shifts the way you look at the world.

  • A Pure Object Oriented Langauge – I would suggest smalltalk for purity, but ruby makes a fine substitute and has more application.
  • A Functional Language – For this look no further than Haskell, and Learn you a Haskell for Great Good
  • A Set Language – Take the time to learn SQL, its a tool most of us use everyday and very few of us take the time to learn properly
  • A Markup Language – HTML + CSS, these are the embodiment of separating data and display, learn them intimately.

Learning these, but more importantly grokking them will color the way you approach problems and solutions. Having a depth of knowledge in a key variety of tools allows you to quickly master new ones, better understand problem domains, and more completely express your thoughts in the abstract.