kids writing code

[caption id="attachment_810" align="alignright" width="311" caption="you doody head you forgot to clean up your EventStruct!"][/caption]

Last night I went out to get some dinner and as I sat in the drive-through waiting for the unbridled joy that is Cain's chicken I listened to the radio. WOSU's All Sides had a piece about child poverty and mentoring. It was interesting and thought provoking, one of the guests said something that rang true and made me think. (Paraphrasing because the audio is currently unavailable) He started to realize that the kids were excited to have him come talk to the class every week, not because they were interested in his stories about the Post Office, but because they wanted to know that someone cared about them. It was a powerful thing to remember, that children need to know that someone cares for them, and that not all children are that lucky.

In writing this blog one of my favorite memories is doing the research to write the teaching post. It reminded me of the heady days of my youth spending hours inside of the amazingly good QBasic help file trying to get something to work, stumbling and bumbling, put beaming with pride and a giddy happiness when I finally got the program to work. These days the amount of programming languages geared towards teaching have only expanded, and systems like Alice put LOGO's turtle graphics to shame (although I still love that LISP-laden turtle).

This started the old gears turning in my head, and although this thought is pre-pre-alpha, I thought I would get some feedback and just jot down what I'm thinking. What if there were an after school program for elementary school aged children where IT professionals donated their time and talent to helping kids learn how to program. Children need mentoring, the IT community has a wealth of talented and caring people, let's put these two things together and see if we can do some good. The logistics of this are a little daunting, but I want to lay out the reasons why now is the right time for just such a program.

Programming is the new literacy. Don't believe me, here is an article entitled Programming is the new literacy. As we move forward into an increasingly wired future, programming, scripting, mark-up, are going to become skills that are normal to have. Children are already more "plugged-in" then ever before, the benefits of understanding the machine they've been using since they were in diapers is apparent. As the information economy continues its march into the 21^st century, people will need these skills. From a simple formula in an Excel Spreadsheet to whipping up a ruby script to do batch processing, these will become the differentiators of tomorrow, helping people achieve.

Hardware has never been more accessible. Moore's Law is a thing of beauty, I just bought a more than capable HP refurb for $150 to act as a media server. OLPC has shown that putting affordable computers into children's hands is possible, and it looks more and more likely that school districts in the Industrialized Nations will be following suit in the next decade or so. Companies routinely donate their old computers which means that if $150 is too much (which it is for a lot of low income families) then you can get a donated computer free. Children can also access computers at libraries and schools for free.

Software has never been more accessible. The number of languages specifically targeting teaching has only been growing. If you haven't already, go read the teaching post, it is a round-up of just a handful of the neat and nifty software meant to help kids learn to program. The learning curve has never been gentler, you can go from a learning language like Hackity Hack (which is based off of Ruby) to the full Ruby language fairly easily, and from there you can explore the whole world of Ruby development from Rails to Unicorn and back again.

Programming is about more than computers. Although the immediate goal of learning to program is to instruct a computer in how to perform a given task, the side benefits are immense. Programming teaches children a structured way to solve problems, learning about control structures teaches the ideas of Boolean Logic, writing formulae increases and reinforces the understanding of mathematics. Programming is also empowering, being able to sit down at a keyboard with nothing more than your wits and a good idea and turn it into something real is an amazing feeling for a child. Programs let children learn and explore, make mistakes and figure out how to solve them, with gentle encouragement and careful guidance a child can turn their ideas into reality, and that's a powerful lesson.

Where to go from here? I'm not exactly sure, the logistics of setting something like this up are a little out of my league. For right now this is just a good idea, I'm at step 3 of the idea ladder. Leave a comment, let me know what you think, if you are a parent, would this kind of program interest you? If you are an IT professional, would you volunteer at such an organization? If you are a business owner, would you support such an organization? If you are a child, would you like to learn to program?

I'm not sure where this idea will go from here, but I'm excited to find out.

ideas

[caption id="attachment_800" align="alignright" width="234" caption="In the future, we will rule this world!"][/caption]

Ideas are interesting things, we have them all the time, we dismiss them frequently, and we value them heartily. Some people don't like to talk about their ideas, don't want people to steal their million dollar brain baby, and I can respect that, but a million dollar idea with zero execution is worth nothing.

Ideas, like misery, love company, if I tell you an idea your brain will immediately start thinking about it, having its own ideas and interpretations. Then you tell me your ideas that my ideas caused and I get more ideas and so on and so forth, this is the basis of a conversation. That our ideas can grow and change organically, that we can piggy back off of each other, this is the basis of our society. But let's get out of the woods of the abstract and into the city of concrete.

What I want to talk about today are those entrepreneurial ideas that we all have from time to time. Those things that you are certain will make you rich and famous, or the ideas that leap back into our minds when we see some new thing, a worldwide pornography distribution network, Tim Berners-Lee stole my idea! What should you do with these ideas, how should you handle them, and why and what and huh.

Every person will have their own way of handling the little lightning bolts that leap into their head but I want to take you through the path that I've found helpful for me.

1. Write it down - I write down almost every business thought I have, no matter how far fetched, and no matter how overloaded with tasks I am. This seems a little silly, if you are actively working at one thing it can even feel disloyal to start thinking about something else, what am I a squirrel easily distracted by a shiny piece of tinfoil? No, in my opinion you can never have enough ideas in reserve. It doesn't take too much time to jot down enough information to be able to recall it later, and it doesn't mean you aren't serious about your current set of priorities. We would all like to think that everything we are working on will always work out, but you will never be sad that you have more ideas to fall back on.


2. Percolate - Go do something else, even if you aren't actively thinking about something, after writing it down it will be floating around in your brain someplace. Great ideas refuse to fall to the wayside, if you find yourself coming back to something in your head more than a few times, move onto step 3.


3. Talk it out - Share your idea with other people, sanity check it, see if they laugh at you. Don't get discouraged too easily though, great ideas can sound crazy and still be great ideas. After discussing it with a few people you can get a handle on how realistic it is and how excited you should be about your new idea.


4. Prototype or Shelf - If you've made it to step 4 you have to look around and prioritize, it's easy to be swept up in the novelty of a new idea, but strive to objectively adjudicate whether or not you have the free time to move forward. If you do, grab some technology you are comfortable with and make a prototype, don't invest too much time or money. If not shelf the idea, keep a short list of things ready made to work on and add this idea to it.


5. Focus Group Lite - If you made a prototype put it in front of some people, or float a pilot program. See how people react, sometimes an idea can sound great until you see it, then you realize some fundamental flaw. If this stage is good then move onto step 6.


6. Jump in with both feet - Get cracking. If you have the time, passion, and indication that people could use your idea, go for it. It will be difficult and you will probably fail, but you will be better for it.

Ideas are nothing without execution, but they are still valuable. Make sure you save your ideas, bounce them off of other people, and if your gut and other people tell you to go for it, take the chance. You may not always succeed, but you will rarely be disappointed that you tried.

blackbox revisited

[caption id="attachment_767" align="alignright" width="275" caption="Oh shit they\'ve miniaturized HAL "][/caption]

The other day I wrote about the concept of the blackbox. I focused specifically on the idea of a blackbox as us programmers think about it. I've been thinking about it more and more though and realized that there are blackboxes all around us. There are processes that our often complicated, confusing, manual messes that our non-programming friends and family have to suffer through. If they knew a little bit of ruby or maybe some batch programming they would be able to save mountains of time and effort, but they don't, so that's where programmers can shine. The problem is that to help our friends and family we have to shine some light into their blackbox tasks and figure out what they do, that's not the easiest task for a programmer to take on.

Recently at work they announced a change to the timecard system that we use, all timecards MUST be submitted by 10:00am Monday morning. The old system was, they should be in sometime on Monday and if not then our very nice receptionist will send out a sternly worded email shaming you into submitting you timecard. Being curious (and being that the explanation was just a few more lines down in the email) I wondered what change had occurred to the system to require this 10:00am deadline. Ends up that our receptionist used to enter this data by hand from the system we enter it in into the accounting software. This was a tedious and error-prone task, once someone bothered to look at it they realized that with a little bit of code they could automate this all and get these programs chatting back and forth like old bridge partners. A couple hours of programmer effort later and now our receptionist is able to answer calls and do all the other receptionisty things that she is great at instead of spending time copying numbers from one program to another.

The blackbox, timecards turning into accounting information, was illuminated and the process was horrible, a little bit of code applied and BAM new productivity abounds. It gets me to wondering, how many other blackboxes are all around me, waiting for someone to shine some light in, see the inefficiencies, and offer up some soothing code. I've given myself a new little game to play when talking to my friends and loved ones, when they start complaining about something that they have to do in their day to day, instead of just offering a sympathetic, "Sucks to be you loser" I start digging deeper. "These reticulated splines are giving you a lot of trouble, how exactly do you make them?" Normally they will reply with a bit of hesitation, maybe even a polite, "Oh, its boring, you don't need to know about that." But if you keep on gently nudging, you can find out enough of the process to help.

It doesn't always have to be by providing code, sometimes just the general nerdy computer knowledge that we have can be incredibly beneficial. It's easy to forget that not everyone knows the little tricks to make the computer easier and more fun to use. I was able to save my mother hours a day by explaining to her that despite what her boss told her, she does not have to shut down Photoshop between opening every file. Until then she had been instructed and believed that she had to wait a good minute for Photoshop to boot up in between every file, opening hundreds of files a day, you do the math. By asking my girlfriend some questions about something she does at work I was able to throw together an Excel spreadsheet to save her a ton of time. The magic of VLOOKUP and some well placed formulas was all that was needed to take a boring repetitive task and make it much simpler and less error-prone.

For those in the computer-know it's easy to look at the computer as a simple tool, something to be mastered and leveraged to make our lives easier. For many people though, computers are blackboxes, confusing little machines that spit out weird error messages and are constantly fighting them to get things done. And there is the other edge of this sword, by shining light into a process blackbox and making life easier you do the double duty of helping illuminate the blackbox for a computer novice. You help show by example that the computer is not mean or frustrating (well sometimes they are frustrating) but just a tool that with careful skill, some essential knowledge, and most importantly a lack of fear, you can make bend to your will.

Go find the blackboxes around you, help someone save 15-20 minutes a day, show someone that computers are not just useful in general but can be made personally useful. You will be a technology hero to them, you will find an interesting puzzle to play with for yourself, and at the end of the day everyone will be better off. Find the blackboxes and start pouring in light, you will be pleasantly surprised at what you find.

simplify

[caption id="attachment_515" align="alignright" width="293" caption="simplicity is sometimes surprisingly complex"][/caption]

I love abstractions, most people do, they allow us to take complex things and wrap them in simple things and everyone is happy. The thing to realize is that there are degrees of complexity and different goals of abstractions.

Programming is one of those things where more often than not our abstractions are really helpful. The problem becomes one of perceived complexity vs. actual complexity. A good example is network protocols.

Network protocols are these complex beasts that let us talk across networks with some degree of certainty. Its really quite the marvel of engineering prowess, man has taken the various blinkenlights and cables and a big ole' pile of Cisco and now you can watch a video of a cat playing keyboard whenever you like. Network protocols were designed to simplify the process of two programs on physically distant machines sharing information.

When you first try to learn a complex abstraction it can seem daunting, UDP, TCP/IP, sockets and fifos and netcats oh my! Sometimes it can seem overwhelming, but take a step back and realize that no matter how complicated a piece of software is, its just moving around bytes.

Perl has a philosophy that at the end of the day, everything is strings. That's why its the glue that holds together the interwebs, because it's just a really good string manipulation language. At the end of the day that's all the internet is, strings floating around, normally between angled brackets.

Like most of the things I write I'm almost certain I had a point... oh there it is. When I started writing prosper it seemed like an impossible mountain to climb. I wanted to write a library that would bridge the gaps between all supported database backends, to have it be a sort of universal data access object.

[caption id="attachment_516" align="alignleft" width="354" caption="This was much easier to think about than the actual problem"][/caption]

I had a few false starts on my project until I took a step back, I simplified my problem domain, and created an architecture that worked. Instead of focusing on the end result of prosper I thought about it in a more abstract way, prosper was a mapper from function calls to string snippets. This isn't actually what prosper does today, prosper is in fact much more complex now than I would have ever imagined when I first started out.

The obstacle that stood in my way the most when starting out on prosper was being overwhelmed and unsure. The problem domain I was trying to tackle was too big, even when I tried solving it i ended up painting myself into a corner by focusing too much on how one specific backend acted. I needed a simpler problem that was more easily solvable, but one that would in the end help me reach my actual goal.

As much as I wish I could take credit for this idea, it's not mine, it's something called Minimum Viable Product. I wanted something that at its core would produce cross-platform SQL, so the first iteration was to make something that did exactly that. If you go on GitHub and pull one of the earlier commits you will see that that's exactly what I built. Over time I have added the ability to execute those strings, connection and transaction management, standardized results, prepared statement support, and much more.

I couldn't have accomplished any of this though if I hadn't taken a step back from the problem domain and looked at the simpler problem at the core of what I was trying to do. I stumbled in the beginning, I've refactored again and again, over the break my good friend Ian took a look at the library and found a whole slew of problems, and I thank him for it. Prosper isn't perfect yet, but it is moving toward being something really worthwhile, and to begin moving it required that I have something, anything, to start with.

So here is my suggestion for you for the new year. If you have some project that you've wanted to do but couldn't figure out how to start, step back from the problem domain and try to find the core of the problem and solve it with the simplest thing that could possibly work. Don't worry about the first iteration, or the first 20 iterations, you have to just get started. Once it is started you can iterate and refactor and maybe throw everything away and start again. No matter what the outcome of the first iteration it will be worth it, the best case scenario is that you can use the first iteration as a core moving forward, the worst case is that you learn a bunch about the problem domain and have to try again.

It's the start of a new year, resolve to start your dream project, because that's the hardest part. Once you get rolling momentum has a fantastic way of carrying you through.

modeling

[caption id="attachment_479" align="alignright" width="225" caption="Just like this, only less beautiful women and more boring data"][/caption]

When solving a problem the most difficult part should almost never be the implementation. Implementing a solution should be fairly straightforward from the solution itself, if it is not, then your solution is incomplete. That doesn't mean that you need to sit down with pen and paper and completely solve a problem before coding, this is an approach taken by some books attempting to teach software development. Some go as far to advocate for an even stricter approach, something along these lines.

1. Model the problem domain with UML or some other modeling technique


2. Translate your modeling into pseudo-code


3. Translate pseudo-code into actual code


4. Realize 2 month project took 2 years to complete


5. Go to step 1 (the problem has radically changed since you took so long)

Of course, I'm poking fun at the books that take such a structured route. Here is a news flash for everyone Programmers are lazy. Here is another news flash (and this might actually be news to some people) Being lazy is good. Not all laziness is good, if it causes you to cut corners and fail to deliver a high quality product, than you fail at life. If however your laziness drives you to find an easier way to do things then "Lazy FTW!"

I have the "joy" of programming Java in my 9 to 5, when you write Java for a living you get used to the absurd amount of verbosity in your code, you also have the joy of Eclipse (notice no quotes around joy) that will write most of your Java code for you. Then there are things like Project Lombok that strive to make Java easier and more fun to write. C# got the memo, and let their programmers be lazy, let's take a look at attributes in a few languages

Here is some C# code to make a class called Foo with a string member called Bar that can be read and written
[csharp]
public class Foo {
public string Bar { get; set; }
}
[/csharp]

They realized people are lazy, let's look at the same thing in ruby

[ruby]
class Foo
attr_accessor :bar
end
[/ruby]

Again, concise and simple, let's look at some Java

[java]
public class Foo {
private string bar;

public string getBar() {
return this.bar;
}

public void setBar(string bar) {
this.bar = bar;
}
}
[/java]

Can you hear it? I can, it's the language architect saying "Just don't be so lazy, write those simple functions, it isn't hard." The truth of the matter is that it isn't hard, in fact Eclipse will happily write these functions for you, just hit CTRL-SHIFT-G. I'm sure there is a point here that I'm getting to, and here it is. I don't want to disparage Java or start a language war, what I want to point out is that Java has a different conceptual model than C# or ruby. C# has the concept of properties and ruby has the concept of attributes, Java doesn't have anything like this, classes have members and functions, nothing more.

The point is that the conceptual models your solution adopts will have huge ramifications on the implementation of the solution. There are many examples of unifying philosophies that make things simpler. Unix's concept that everything is a file, C++ concept of streams, Erlang's pervasive share-nothing message passing, ruby's duck typing. These are core concepts that have profound and far reaching consequences.

Working on a new side project I recently was struck by a way to simplify a complex data structure by adopting a new conceptual model. Creating an internally consistent, elegant conceptual model is the most important thing you can do for a project's success.

Conceptual modeling is a hard thing to get right, go into too much detail and your model becomes rigid and brittle, go into too little and the model can be impossible to implement correctly. Making a good conceptual model is like making a good analogy, there are a few hallmarks to a good conceptual model.

• The conceptual model should simplify the problem domain. Files and folders greatly simplifies the concept of a hierarchical file system by relating it to something commonplace.


• The conceptual model should not be overly complex to translate into an implementation


• The conceptual model should be uniform and consistent, if you find parts of the problem domain falling outside the conceptual model or feeling "tacked on" you should rework the model

The next time a project seems stuck or overly complex, instead of refactoring code or attempting to throw another library at it, take a step back, look at the big picture and refactor your conceptual mode.

decompress

[caption id="attachment_472" align="alignnone" width="450" caption="Get ready for the feats of strength"][/caption]

The holidays are upon us and no matter what holiday your particular sky god has you celebrate (Festivus for the Rest of Us!) there is one thread of humanity that binds us together at this time, days off from work. When you have some time off of work you can spend it doing any number of worthwhile things

• Drinking egg nog until you black out


• Eating your weight in sugar cookies


• Having that same argument with your family that you've been having for the last 10 years


• Watching 24 hours of A Christmas Story


• Spending quality time with friends and loved ones


• Living through the same day over and over and over, á la Groundhog's Day (Best saved for the actual Groundhog's Day)

If you are reading this blog there is a good chance that you are some sort of programming nerd, its ok, I don't care what the New York Times says. As a proud nerd you have probably heard of some sort of technology that interests you, maybe clojure has piqued your curiosity, or you finally want to learn that "rails" thing all those young whippersnappers keep talking about. I would argue that this can be a great way to decompress, if you do it right.

First off, find something different than what you are used to, if your 9-5 is .Net don't spend your precious free time learning more .Net, that's stupid. Go find something radically different, maybe look at a functional programming language, go find that weird kid in the corner and talk to him, he probably has interesting stories about fire. This might seem like a waste of time at first, but it's not. It's all too easy to get locked into an ecosystem, doing the same thing day in and day out, to get comfortable there and to start thinking that your way is the only way or the best way. Reading about other technology outside of your realm might not have a direct benefit to your 9-5, but you may gain a perspective or understanding that would be incredibly difficult to get from your standard frame of mind.

Second off, this isn't work, this is fun. You are allowed to make mistakes and change your mind. If you work through a tutorial or get done with the first chapter of something and find that you really don't care, then go find something else, the software world is full of interesting things. The thing is, only stop if you grok the subject and dislike it, don't necessarily stop just because you don't get it at first.

[caption id="attachment_475" align="alignright" width="300" caption="What? Caroling? No fuck that, I got some erlanging to do!"][/caption]

Third off, this is just to whet your whistle. Don't ignore your loved ones, squirreled away with your Beginner's Guide to Erlang because you've fallen in love with the idea of massively parallel systems. Take this time to investigate several things, learning the basics and setting up your love affair for the next few months. Then make sure you tell the people you care about that you love them and eat too much food and do people things.

For me this break will be about Rails. I've followed rails for a while, I've always been impressed with it, and I've had a few false starts. I've gone through the Getting Started tutorial more than once. I'm a php guy at my core, but learning how other people do the web is worthwhile. I've started the adventure already and think that this time it might stick. I have a 2 hour car ride up to Cleveland and back that I plan to fill with listening to Rails podcasts.

---

That's all for now, go relax and decompress, that's what I plan on doing for the next 4 days. As a side note I will probably not update during the holiday break so if you obsessively check or your rss feed gets lonely don't worry I will be back on the 28th.

pushing

[caption id="attachment_368" align="alignright" width="300" caption="cupcake dispensing button"][/caption]

I have been working on prosper for the last few months, I started thinking about it in early October and according to GitHub my first commit was October 22nd. This project has been great fun so far and I'm not even close to a 1.0 release yet (right now prosper is at 0.6 well on its way to 0.7). I have learned a ton on this project that I would have never guessed before I started.

• The joy of GitHub


• The terror of phpDoc


• The prodding of friends


• The camaraderie of other developers (Will Bond and Jeremiah Peschka)


• The vulnerability of releasing the project


• The drive to keep improving

I completely underestimated the amount of work prosper would be, and I don't mean coding (although coding has eaten up a large chunk of the time I normally fill with playing Borderlands). I didn't realize the amount of work it takes to manage even a small project like this. GitHub has been an amazing resource, but at the end of the day it is a tool, and you need to spend time learning how to use it and populating it with data. Writing up documentation, reading documentation, creating examples, running tests, working with collaborators, discussing technical problems, it has been a mountain of unexpected stuff. Now I'm not complaining, this was the challenge I wanted, I'm learning a ton of new stuff, making great new connections, and pushing myself in ways I never have before. One of the most important new hats I'm learning to wear is promoter

Let's say you have a great idea (like a standardized php database abstraction layer), and you decide to invest your time and energy into it. Great, you start coding like a madman and you have something working, you are working out the kinks, enjoying it, really making something worthwhile. After a while you have this project to the point where you think others might be able to use it, what do you do?

1. It's too much work to do anything, just let the bits sit on your harddrive


2. I need to share this with people, I'll toss it on GitHub / BitBucket / SourceForge / etc


3. I want to promote it


4. I'm going to get others involved

Those are the steps that I went through, and I would imagine a lot of people do, really I'm at step 2.5-ish, I created some pages within WordPress for prosper, but I plan on spinning out a standalone website for prosper at some point. The list looks easy but the problem is that you have to push yourself, because each step is costly.

To go from step 1 to step 2 you need to push past that voice in your head telling you to apply more polish. You need to push past any indecision or fear of criticism and get your code out there. The next step is to promote the crap out of your project. This step is difficult because how do you even go about it. Here are some ideas.

• Create a sample application using your project


• Give your project a home and shamelessly link to it


• Promote on reddit, Hacker News, etc.


• Get friends more famous than you to push it, if you don't have famous friends, start sending out emails, the people that I've talked to have been really great


• Submit your project for review in any pertinent technical website (like PHP5 Magazine, which may actually be defunct)

For step 3 you have to push others, push friends, and push yourself to get your project on people's radar. Now for the next step, getting others involved. You should have created some connections and hopefully some users, enlist them to make your project the best it can be. User's can submit bugs, feature requests, and patches. Other developers can polish up bits they are interested in, as my good friend Jeremiah did. Getting more eyes and ears and noses in your project let's you refine and build, spreading complexity around.

The point of everything is that you have to push. Even great ideas, great code, great projects can fall to the wayside if no one pushes. Promoting the work you do is nearly as important as the work itself, if no one ever uses your code, no one will care about the months of effort you put into making it beautiful. Get out there and be passionate, genuine, and don't stop pushing.

---

Tomorrow I will be picking up the gauntlet that Jeremiah Peschka threw down today in What is Your Biggest Weakness? Tune in tomorrow to see what my biggest weakness is, and see who I challenge next.

murdering your baby

[caption id="attachment_356" align="alignnone" width="370" caption="don\'t worry, no babies were harmed"][/caption]

Yesterday my friend Ian sent me a tweet about prosper

@ihumanable I'd be more interested in using Prosper if it provided support for true prepared statements instead of concatenating strings.
6:29 AM Dec 7th - pian0

With that my baby was born, the baby was a version of prosper that utilized prepared statements where appropriate. Prosper's main functionality has been coded for a while and the bulk of the work I've been doing as of late has been testing, improving backend support, and adding new functionality. The nice thing about this kind of work is that you don't have to go mucking around in working code, you are just fixing broken stuff and adding new functionality. The idea of adding prepared statements made me a little queasy, I had briefly looked at it when I was starting prosper but decided that they were so varied that for the first attempt I would just avoid the headache. What's the problem you ask, let's take a look at this feature table real quick.

Database	Supported by Prosper	Can Support Prepared Statements
dBase	YES	NO
DB++	NO	NO
FrontBase	YES	NO
filePro	NO	NO
Firebird / Interbase	YES	YES
Informix	YES	YES
IBM DB2	YES	YES
Ingres	YES	YES
MaxDB	YES	YES
Mongo	NO	NO
mSQL	YES	NO
MS-SQL	YES	YES
MySQL	YES	YES
OCI8 (Oracle)	YES	YES
Ovrimos	YES	YES
Paradox	YES	NO
PostgreSQL	YES	YES
SQLite	YES	NO
Sybase	YES	NO
Tokyo Tyrant	NO	NO

As you can see the support for prepared statements varies in the Vendor Specific Database Extensions of php. There is also the fact that prepared statement support is poorly implemented in several extensions, they can be coded around but it adds a good deal of complexity. Despite all the reasons not to implement prepared statements, safety, speed, and correctness dictate that I should at least give it a go.

Yesterday and today were my go, and I met with some success. Prepared statements are not all that difficult to implement for a given backend, throw in some question marks, call the correct bind function, and you're off and running. The real difficulty is the cross-platform nature of prosper. I wanted prepared statements to be a first class citizen, I didn't want to decrease any existing functionality, I wanted to not overly complicate the way prosper works, and because there are 11 adapters that need to be upgraded, I wanted it to be simple to add this functionality to a given adapter.

I worked and toiled and toiled and worked, I tried hacking something up to make the MySQL adapter work, ran into the bind_results function and screamed at it for a while. Then I got out some paper and drew out some diagrams, thought about sample code. Then I went to sleep. Then I woke up and in the shower pondered the proper syntax for passing around typing information and the division of labor for transformation. Then I hacked on it some more and wrote a quick test. Then and this is the most important part I realized I had done it absolutely backwards.

I had some clues that stuff wasn't working out right, I hit a point where I would either need to embed an if statement in every function of an adapter or have a duplicate function. I thought that with some clever coding I could shove this down into the base class, it wasn't great but it was working. Then I saw another red flag when I realized that the processing in the where clause was identical to the processing in the values clause, and I applied some refactoring. This is when I realized that there was a single function that I could have modified and had the whole thing work much more elegantly.

That is when I had to come to the decision to murder my baby. I had painstakingly worked out the kinks for two days, traveling far down this road, touching a bunch of code, and now I realize the best way forward is back. The best thing I can do right now is to revert my changes to Monday morning and lose 2 days of work, and that is great!

It's not the best outcome, in an ideal world I would have seen this solution before and applied it and not wasted 2 days. The thing is that I've learned a great deal, I've come up with a much better implementation, and I've been reminded of an important lesson, never be afraid to throw away code. The code I wrote is adequate, it works well enough, but it is far from optimal. I could keep going, head down, plowing away making as many problems as I solve trying to build a house on an unsound foundation. The point here is to pay attention to those red flags.

The other important point is that sometimes you have to actually try something to find the thing that will work. You may lose some time, but even after sitting down with pencil and paper, thinking long and hard, the optimal path didn't come to me until I walked down the wrong road. That's just life sometimes as a software developer, you have to learn to live with it.

I will continue working on prepared statements for prosper, and I hope that by 0.7 or 0.8 they will be implemented and in there. I still question the syntax and think that I can clean it up, right now the plan is for prosper to support unnamed parameters (?), named parameters (:name), unnamed typed parameters (%i), and named typed parameters (:name%s), but all this seems like a little much. Good thing prosper hasn't had a 1.0 release yet ;-)

spinning wheels

[caption id="attachment_295" align="alignleft" width="251" caption="keep pushing that boulder"][/caption]

Back from Thanksgiving, nice break, hope everyone had a good holiday. With the long weekend came some time to eat turkey, spend time with my family, and reflect on life. I've been thinking about what I want to ultimately accomplish in life and how to get there. The end goal is to work on complex technical problems and produce something useful for humanity.

I spend a good amount of time on Hacker News which is a great place to find out about new technology. It's a fantastic community where entrepreneurs and programming geeks get together and talk about technology and startups. It's the kind of place that incubates ideas that become the next twitter or youtube. Spending time there has made me think that I can do more, do better, it was part of the drive to make prosper.

The problem is that life doesn't happen in a bubble. You have to buy groceries, pay the rent, and keep the lights on. So I've found myself at an odd cross road, I'd rather not continue doing business programming, but I can't stop. What is a person to do? How does one pursue their dreams while maintaining financial security, is it even possible?

For a long while I've believed that you can work a 9-5 to keep the lights on and then work on a side project in the evening. The problem that I'm now finding is that any project that you can hang your hat on and make a living with is going to require more work than what you can give it in the 4 or 5 hours after you get home from work and before you go to sleep to get up for work the next day. Once you throw in trying to have some semblance of a life, it becomes nearly impossible to give a side project enough love and attention to make it work.

I've still been working full bore on prosper and its sister project that has yet to be released. The problem that I face now is this ever creeping feeling that I am merely spinning my wheels, and the encroaching danger of professional burnout. Prosper has yet to see any real adoption, which is not surprising its not ready for anything concrete yet, it is unproven, and it is still in a huge state of flux. The 0.5 release and the current bleeding edge on GitHub are fairly different, with the bleeding edge being a fair bit better.

There is no use moping about all this, so I need a plan to move forward with. Can I quit my day job to focus on the side projects, no. Should I give up on my dreams, no. What is the way forward then? Normally I would double down, work harder and push through. The problem is that I think I slipped from the first stage of professional burnout (Physical, Mental and Emotional Exhaustion) to the second stage (Shame and Doubt), and pushing harder, doubling down, may only accelerate this process.

I still believe that I can change the face of PHP database access, that my library can provide a hugely needed service to hundreds or thousands of PHP developers. I still believe in my ability to create useful technologies and solve difficult problems. So I'm creating a list of things to accomplish in the hopes of defeating my professional burnout.

• Re-institute a workout and diet regimen - Long hours at work and on projects have caused me to spend too many hours sitting around and running to McDonald's or Wendy's for a quick bite to eat.


• Create concrete project goals for prosper - So far development on prosper has been haphazard, I'll get some idea and then work implementing it. The problem being that this leads to an almost manic-depressive like development schedule. When there is a new feature to implement I could spend 6 hours working on it, then have days and days of nothing until a new idea springs up.


• Make time to relax - I find that I spend most of my off-time working on prosper or its sister project. The other "down-time" that I have is spent reading technical articles and ebooks about programming. This stems from my deep love of programming, I do enjoy reading about lisp for hours, but I need to rekindle some of my love for other subject matters, too much of anything is a bad thing.


• Reflect on the good - Too often I spend time thinking about the negative. There are many great things that I take for granted.

Like GI Joe said, knowing is half the battle. This post is more about coming to terms with the difficulty that I'm currently facing, but I hope that it can help others in a similar position. No one is going to hand you your dreams, you have to fight and scrape and kick and scream to make it. It is difficult grueling often thankless work. It's not easy, but if you want more out of life than a paycheck and a cold grave you must fight for it. The struggle takes it toll on everyone, but by being cognizant of the dangers, and recognizing that you are not impervious to the grind, you can make it through, and hopefully make something unique and beautiful.

refactor

[caption id="attachment_292" align="alignleft" width="225" caption="google thinks this means refactor"][/caption]

I've been working a lot on prosper lately (this means that if you want to play around with it, get the bleeding edge on GitHub). I recently added a lazy loading feature, mostly to facilitate unit testing, and pretty soon I will be adding some unit testing. I was able to take care of some things recently that have bugged me for a while, and its because of ruthless refactoring.

Refactoring is not black magic, it just means taking some code and reworking it, rename a function here, encapsulate some functionality there, done. The sticky part is that refactoring is a compounding problem. Things that should be refactored build up on each other, so if you put off refactoring for too long you will have a real mess on your hands. Refactoring can be painful but should never be put off, you see a function named poorly but know that it is used in 20 places, get it now, don't put it off, because by the time you get around to renaming it, it will be in more places.

A good IDE will help you in your refactoring process, the one that I love is (surprise, surprise) Eclipse. Eclipse is brilliant at refactoring, probably because it keeps semantic knowledge with symbol names. Rename the function foo to bar and you don't have to worry about Eclipse destorying all those variables named foo (ps. if you have variables named foo you have refactoring to do!). Eclipse (and other IDEs) are great at all kinds of refactoring, renaming, extracting and encapsulating, pull up, push down, etc. Get to know these tools, get comfortable with using them, and refactor without fear.

Wait, change big chunks of code without fear, how!? Well you should have tests, be they unit or functional. I'm introducing unit tests into prosper, but for the time being I have a local version of todo list case study. The todo list application is pretty good because it exercises all the important bits, if I change something and everything in there keeps working, I haven't broken anything too badly.

The reason I want to introduce unit tests though is that I've introduced regressions even with the todo list humming along, some dark corner of prosper has started shooting out unicorns, but I haven't noticed, until I see some bit of code that I know can't be doing the right thing. Test coverage allows you to refactor without fear, and if you want to have a living project that people might someday use, you need to refactor without fear to keep things current.

---

That's it for the technical part of this blog post, I would like to announce a few things though.

• The move to GitHub has been completed and I'm starting to get into the workflow of using it now.


• The new skunkworks project is nearing a beta release, so keep an eye out.


• Development on the new project has spurred improvements in prosper, there will be a point release (0.6) soon


• There probably won't be a post tomorrow as I'm traveling with Heather, my beautiful girlfriend, up to see my family in Cleveland.

That's all for now, I will have something up Black Friday more than likely, until then, Happy Turkey Day everyone, safe travels, see you after I put another couple of pounds on.

discomfort

[caption id="attachment_284" align="alignright" width="300" caption="was the collander really that hard?"][/caption]

I am an American, which means that my life is constant bombardment of people offering to make it simpler, faster, easier, and more comfortable. Watch an hour of tv and count the number of times people are trying to make your life easier and more comfortable, its quite a few. The problems they solve aren't even real problems, they are imagined problems that we've been convinced are real. I used to think these problems were real too, I didn't have enough time, I didn't have enough skill, I needed the pre-packaged solution that was quick and ready in 5 minutes.

Then I woke up one day and realized that I had been swindled by a bunch of bullshit.

Who has 15 minutes to make pasta for dinner?! [Show woman dumping pot of scolding hot water and noodles all over herself]
There's just not enough hours in the day!! Buy our microwave-licious pasta bowls!!!

You know who has 15 minutes to make pasta, everybody does. Want to write a comment saying there is no way you could free up such time, well fuck you Mr. I-have-time-to-read-a-blog-and-post-a-snarky-comment-but-somehow-can't-find-15-minutes-with-both-hands-and-a-flashlight. At this point though, we are all thinking, am I trying to make some sort of point about pasta or is this going to get around to programming at some point?

Well thanks for going on that side-rant with me, let's look at what in the world I'm trying to get to. Being a programmer I like to be comfortable, I like to work with the languages I like, and the tools I know, and the frameworks I understand. It makes sense, people are more productive when they are working with the tools we know, that's why we have holy wars about what language is better and which framework to use, we invest some time getting our nice comfy language set-up just the way we like it and we look at people sitting on uncomfortable languages and wonder what the hell is wrong with them.

The problem with being comfortable is that its hard to learn and grow when you are comfy. You know the language, you might learn some edge cases here or there or uncover a new feature or bug every once in a while (and this is important too, its important to be a master of something), but new learning is rarely done this way. Its very hard to learn new things by doing the thing you already know how to do day in and day out. Yesterday I decided to do something new, and it was uncomfortable, but I've started learning and hope to learn a bunch more.

What was this horrible discomfort that I suffered, moving my code for prosper from Google Code to GitHub. You see, I've been using Subversion since college, when one of the smartest software developers I know, Ian Potter, introduced me to it. I had heard some stuff about svn before and compared to the source control system we were using (a folder called test and a folder called production) had determined svn would be a step up. He set up svn and patiently answered my questions of which code was on my machine and which code was on the server over and over again until my brain finally wired it up.

Moving to svn was much more complicated than the tried and true 2 folder methods, but the safety, history, and concurrency that svn offered was more than worth the week or two of learning the new system. In my career so far I've gotten to use cvs, svn, and vss, they are all similar concepts, there is a central repo and you can commit, update, branch, merge, blame, etc. This is how source control works in my brain, and I am completely comfortable with how this all works.

Well svn is no longer the new hotness, git is in big time, and a good portion of its popularity can be attributed to GitHub. GitHub is the facebook of source hosting, its a really great site to host your project on, most interesting new projects are hosted there, and the social aspect allows people to easily interact with you and your project. I've had a GitHub account for a while, and I tried it out before, only to go back to the comfortable embrace of Google Code and svn.

[caption id="attachment_285" align="alignleft" width="300" caption="who could resist octocat?"][/caption]

So why move to git, just because its shiny? Well, GitHub is almost enough of a reason, but the distributed nature of git, the increased popularity of git, and the ability to quickly make new branches and merge them back into trunk, make it worth learning. If I want to continue being active in a community that more and more relies on git, its probably best to learn it.

I've taken the first step, I've moved my stuff over to GitHub and I've got git up and running on my laptop, I've been able to push some changes upstream and over the next few days I will be reading the excellent help that GitHub provides you. It will not be comfortable, I will probably be scratching my head for a while, wishing to go back to the centralized repo that I know and love. I will more than likely treat git like svn for a while until I "get it." But I've decided to stick it out, to live with and own my discomfort and to learn this new thing.

Here is my challenge to you: maybe you've read a few things about a new technology and its interested you, maybe you've even taken a few trembling steps into the new technology, and you've walked away or put it aside. Go back to it, jump in head first, don't look back and don't give up. The great thing about technology is there is usually a manual to read, a community to turn to, and our old friend Google. Make yourself uncomfortable, you might just learn something.

division of labor

[caption id="attachment_280" align="alignright" width="216" caption="cartoon labor"][/caption]

When building or analyzing any system of significant complexity the most important thing to determine is a proper division of labor. The entire idea of n-tier architecture is built on dividing labor up into the appropriate tiers and keeping them cleanly separated. For anyone that's ever worked on a real world system half of the difficulty is caused by one layer leaking into another and the other half is getting around the separation caused by separation.

Despite my last sentence, division of labor is a necessary and good part of design. When done right it allows you to know where functions, variables, and constants should live, how things should interact, and who is the system of record. This is why it is imperative to decide beforehand or shortly into a project what the lines of demarcation are and who is responsible for what.

Prosper is one of a group of libraries, with well defined divisions of labor. This allows the libraries to be decoupled, and also has the added benefit of letting me know when I'm done. When I found myself adding functionality to Prosper the other day that I knew belongs in the next library, I realized that it was time to officially start the next library. So a new skunkworks project is moving ahead full steam, it contains 2 parts that work together, and so again requires a well defined division of labor.

Just because work has begun on a new library doesn't mean that Prosper is left out in the cold, yesterday I added support for the deprecated mysql library, standardized construction, and added better support for native functionality. If you are checking out Prosper, you can follow the latest development by pulling from the svn repo.

Back on topic though, figuring out the division of labor is the most important part of any analysis or design work. We recently at work had a 2 hour long discussion about order numbers. It went something along the lines of this:

BA: This order number comes from the Mainframe
Expert: No the Application creates that number
Dev: So, what does the SOA layer need to do?
BA: Generate the number
Expert: No, do nothing, the Application will automatically do it
Dev: Wait so who is responsible for creating the order number, and if its not the Mainframe why is it making one?
Expert: The Mainframe always made that number and the Application has always ignored it.
BA: So we will make it in the SOA Layer?
Dev: Who is in charge of making the unique identifier order number?!
Expert: [shrug]?
BA: [shrug]?
Dev: Let's decide that first

Explicit division of labor requires you to pull the unspoken assumptions everyone has about the system out of the silence of our own minds and puts it into the blinding daylight. Suddenly communication is smoother, arguments come to an end, because there is some record to consult to help guide decisions.

Draw out your explicit divisions of labor, don't carve it in stone though, if your original design ends up being too inflexible, allow it to change, but again, bring all the unspoken assumptions back out into the open. This allows you to cleanly define what piece is in charge of what function, keep layers from leaking into each other, and make for smoother development and analysis.

dogfood, terror, and tweets

[caption id="attachment_251" align="alignright" width="300" caption="too literal"][/caption]

Yesterday I released my new library Prosper (in case you hadn't noticed the new menu entry at the top of this blog). It was a ton of work, way more work than I ever expected, but it was worth it. Prosper is now out the door and ready for human consumption, I've been using it all day on a fun little project, mostly playing around with the twitter API (which I've done before but never from php).

I was talking the other day with the esteemed Rick Kierner about the upcoming CodeMash convention. Since I work for an amazing company that is sponsoring the event, I get to go for just about free. I plan on going to the precompiler sessions and that day comes out of my pocket, but its a small price to pay. Rick is taking care of the nitty gritty details but in the end I will have to give him some cash money to pay for the precompiler and the first night's hotel room, he decided to use BillMonk to record the debt and keep everything straight.

After perusing BillMonk for a while I decided that I really liked the site, its a cool idea, and I thought to myself, "hey self, now that tipjoy is defunct could there be a space for me to make my mark." (Side note, I often think hyperlinks at myself). Rick and I bounced some ideas off each other and at the end of the day decided that there really wasn't a good business in what we wanted to do, so we abandoned the thought and moved on, c'est la vie.

Today though the idea kept bouncing around in my head, really its been bouncing since we first started talking. Today I finished my proof of concept for my new minimalist bill tracking system, currently dubbed cha-tweet (a portmanteau of cha-ching and tweet). I'll outline quickly the concept behind it, a rough approximation of its implementation, its status, and what the title has to do with anything so far in the post.

The idea is basically this, you can tweet a specially formed tweet and cha-tweet will aggregate those into a nice little summary of who owes you cash and who you owe cash. The tweets look like this

The debt cha-tweet

@I_owe_this_guy_money > $5 lunch: delicious sandwich!

The give cha-tweet

@I_gave_this_guy_money < $5 lunch: mcdelicious

The basic idea is that money comes out of or goes into the username to or from you, respectively. It's a simple syntax that lets you sort by debtor/debtee and by type of debt. Since it starts off with the @username syntax it only gets displayed (by default) to people that know both of you and would maybe care, and its easy to find by the service because it is treated by twitter as a reply. The system works fairly well, and I'm happy enough with the concept.

The problem was that to create an accurate summary it had to go get and process the entire tweet stream, which can take a long while, and assuming that most of the tweets in a users tweet stream will not be cha-tweets, there is no need to do all this processing everytime (and in steps sexy miss rdbms). So, throw a database at the problem, store the seen cha-tweets and operate on them, this has now been implemented, it took one hour, and I used prosper to do it.

So how was it? Really easy, I stole the configuration from the todo list project, switched around the credentials and the schema name, and was off and running. Everything was working well until I tried to update something and Prosper spit up a bunch of non-sense at me, and my heart sank. Did I just release some library full of horrible bugs and will be mocked endlessly, the cries of n00b and pwned reverberating so loudly as to drive me mad?! No, I just don't know how to type so instead of writing this
[php]
Prosper\Query::update('user')
->set(array('since' => $since))
->where('id = :id', $_POST)
->execute();
[/php]
I wrote
[php]
Prosper\Query::update('user')
->set(array('since' , $since)) //WHOA!
->where('id = :id', $_POST)
->execute();
[/php]
Changing that double arrow to a comma makes a big difference, and causes prosper to correctly try to set `0` to 'since' and `1` to 'some_huge_twitter_id_number' which is what I told it to do.

Crisis averted, my library still functions properly, hip hooray!

• Is it easy to use? Yes, I found that it cut down on my development time considerably.


• Is that because I wrote it and have no learning curve? Quite possibly, I'm not going to rule that out.


• Is the code easy to read? Yes, its fairly straightforward crud stuff, made much simpler by prosper.


• Did I learn anything eating my own dogfood? The verbose function is awesome! I wrote the verbose function in the beginning as a simple debug / sanity check of sorts to make sure that things were being translated and serialized correctly (pro tip: the magic __toString function will print the sql statement that will be executed). During development though it was incredibly useful to be able to switch the call to execute for a call to verbose and immediately see at a fairly granular level what was going on. This got me to thinking how much prosper needs some official documentation, and that will be my project for the next week or two.

In the end I have a nifty little twitter gadget, I will probably be hosting it somewhere soon so keep an eye out for that, but more over I have some more experience as an end-user with prosper and a renewed energy to write the official documentation.

---

I'm also adding some stuff to the blog, there are now social media icons, the rss feed link got a new friend mr. twitter link, and there are some backend changes for speed and stability. This is another round of blog tweaks and that is the best time to have your opinion incorporated into the blog's overall look and feel, so comment away!

leaps and bounds

I keep talking about (more like won't stfu about), the sideproject I've been working on. Today I added several draft pages to this blog containing documentation and release information, I'm expecting to have the actual rollout sometime next week. I've made a flowchart to show you how my mental process worked so far on this project, and where I'm at now.

[caption id="attachment_131" align="aligncenter" width="331" caption="how my brain works"][/caption]

Most of the time I get stopped in the "will it ever be any good?" decision, it returns no, and I scrap my code, and wait to have a worthwhile idea. This time though, somehow, I've managed to move past that one, and for the last 2 weeks or so have been spinning around the "is it any good?" -> "no" -> "refactor" -> "is it any good?" -> ... loop. I've been tweaking this or that and in my head there was still so much to do before releasing.

Today though I've found myself writing up release information and documentation, and I came to realize that the ever present list of things to add or get working or refactor had been brought down to nil. I'm out of code work to do for the time being on this project, the best thing I can do is release. There seems to be this huge leap though from hacking to releasing, for me at least. I can sit all day adding features and refining APIs, but I realize now how frightening it is to put your work into the wild and try to promote it.

I feel this anxiety doubly compounded because I didn't write an application where the code, even if open sourced, is neatly tucked away behind the scenes. I wrote a library, with an interface and code that if it gets any kind of adoption, people will probably look at, curse at, laugh at. Really though, there is nothing to do but put it out there, track the bugs, iterate, and make it something I can be proud of.

Next week I will be officially releasing this side project, my hope is Monday morning. I want to write up some great documentation, explanation, set up bug and feature tracking, set up a forum, and move the project over to github, because github is the official hotness. So this is a head's up, watch out next week because big things are coming.

orm and sql

I've been working on a side project in earnest lately. It's all kinds of PHP fun and I'm enjoying learning the ins and outs of PHP 5.3 as well as relearning some of the stuff I already knew about from my PHP glory days. I've been looking at various different ORM solutions to use with my project and I'd like to take some time to review them, explain why I chose none of them, and what I'm doing instead. For the non-technical in the audience, ORM stands for Object-Relational Mapper, its a piece of software that allows you to save parts of your program to and load them back from a database, supposedly quickly and easily.

• Doctrine
  Doctrine is the 800-pound gorilla of PHP ORM solutions, it has it all, and then some. It is an ORM sitting on top of a DBAL (Database Abstraction Layer) which leverages its own query language DQL (Doctrine Query Language). It can be configured in any number of ways, supports all kinds of backends, is mature, stable, and feature rich. That's all the good of Doctrine, the bad is the learning curve. The manual for Doctrine is 30 sections long, each section is quite a bit to take in. This is great if you are doing an enterprise level program, but for my project Doctrine was overkill.
• Flourish Lib
  This is not an ORM solution, although it does contain one. Flourish is an unframework, and a really, really good one at that. If you want to shut someone up who says you can't write good code in PHP, send them to Flourish, the creator Will Bond did a tremendous job with this unframework, and I still plan on using large parts of it. The ORM layer is actually really nice, there is a bit of a learning curve, and at the end of the day I decided that it did too much and polluted my models too much. Flourish though is definitely worth learning, the website also has great best practices to follow if you are building a PHP Web Application.
• php.activerecord
  Based off of the widely successful Ruby on Rails ActiveRecord class, this project aims to bring the ease of Rails database interactions to PHP. It does not attempt to be a PHP on Rails framework, there are plenty of those, its just a great implementation of the ActiveRecord pattern. The documentation is also fantastic, covering the essentials and letting you jump right in, it feels like there is no learning curve at all.
• RedBean
  This is a complete departure from normal ORM solutions. In a normal solution you are cognizant of both the object model and the relational model, the ORM acts as a pleasant interface for interactions. In RedBean you are freed from having to know about the relational model, in fact you are allowed to let the relational model change on the fly. Need a new attribute for that object, don't worry about migrating schemas, just slap it in there and let RedBean figure out the rest. It is definitely an interesting idea, and it is maturing quickly, but I was wary of using it because of the overly fluid nature and the business constraints of my project

Those are the most interesting ones I investigated, I investigated quite a few other ones, but these were definitely the cream of the crop. None of them fit my project, but my project is a little bit weird (if you keep reading this blog you will no doubt see it one day, unless something shiny grabs my attention and I wonder off). If you are looking for a really powerful ORM with all the bells and whistles, check out Doctrine. If you are familiar with ActiveRecord, php.activerecord is a fantastic implementation. If you are programming PHP at all, take the time to read through Will Bond's amazing Flourish Lib. If you need some lightweight persistence or want to dabble in some object-oriented databases, give RedBean a try. Really on that last one, if you are even at all interested by technology, check out RedBean, it is a little young but shows amazing potential and is a great example of thinking outside the box.

So what did I decide, well I decided I don't want to use an ORM layer. ORM didn't fit my use case, I was only experiencing developer pain trying to shoehorn it in there. I decided that what I needed was something a little different, and I'm currently developing exactly that. So what is this mystery project that I'm working on, its a couple different parts that work together, but I decided that all I really wanted was the following list of things.

• Cross platform SQL
• Automatic CRUD
• Lightweight library

So I'm writing them, and I will be releasing at least part of it soon, once I get it to a point where it does something, then expect a blog post with trumpets and whatnot. I conceived the project structure last night and began coding, I was able to put in 3 hours of work and got a very nice proof of concept running, but it is still all sharp edges and scuffed surfaces.

Stay tuned though, I hope to have something people can put their fingers on soon. I think there is a need for the lightweight components that I'm building, as a platform for future innovation and because after 3 months of looking around I couldn't find anything out there that did what I needed.

project documentation

This post is about documentation, not source code documentation, but project and process level documentatino. I've spent the last 3 days working on a quick side project at work. There were 10 tasks, none of which were very complicated, the time spent tackling these tasks was about 5 or 6 billable hours. The time spent figuring out how to deploy these changes was about 3 days. The problem, project documentation

Scattered Information
Like some sort of 80's Nintendo Game I had to find the various colored keys to win the game. One developer knew the ftp server's ip address, another the username, maybe a third the password. It didn't help matters that this was a fairly complex site made up of multiple components (third-party blog, storefront, cms) each with their own credentials. Collecting this information was the first hurdle to leap in getting the code and getting the job done. It took a solid afternoon of pinging different parties but I finally had a list of keys, the blue door, the red door, even the green glowing door could all be opened!

Out of Date Information
Then came the crushing realization, as I found that the red door was rusted shut, the green glowing door didn't use a key but a magic potion, and no one could remember exactly where the hell the blue door was even located. The information was out of date or just plain wrong, more time wasted pinging people to get updated information and missing chunks. But after another day of haranguing I finally confirmed that the doors could in fact be opened, that night visions of tables and source code danced in my head.

Misplaced Information
This isn't really anyone's fault. I was working on a type of system, let's call it a foo type system, this particular foo system had been customized for client bar. I looked in the foo\bar\ folder for documentation and came up empty-handed. I assumed that there was no documentation and so created some there to collect up the hard earned bits and pieces of information I was able to pull together. Being proud of my new documentation with things logically laid out, I reported to my fellow developers the great leap forward in documentation technology I had developed. I was told there was similar documentation in the foo\ folder, why no one mentioned this to me earlier when I was pulling together this information is beyond me. But it didn't make sense to my brain, if there is a foo\bar\ folder why isn't foo\bar\ information in it, why is it in foo\, ah!

So what is the solution? Knowledge Base, Sharepoint, Wikis, Word Documents, what to do? I don't think that any one of these things by itself is a solution, but I do have some ideas.

Convention over Configuration
If you've ever played around with Ruby on Rails you will know the great joy of feeling at home in a rails project. Where are my models?! app\models\ that's where they always are, that's where they belong. I think adopting a standard documentation layout structure would be useful. Here's an idea (off the top of my head, so its not very polished)

• project-name\documentation - Root of the documentation
• project-name\documentation\bootstrap - How to get started, pulling the project from source control, initial builds, dev box configuration
• project-name\documentation\credentials - IP Addresses, Username, and Passwords go here
• project-name\documentation\database - Everything you'd want to know about the database
• project-name\documentation\deploy - Deployment specifics are here
• project-name\documentation\vendor\* - Third party documentation goes in various folders here

It's not perfect but its a start, really the important thing would be to have some sort of standard and stick to it.

Wikis
I like wikis, I think they are neat. Your documentation is easily editable, so it's easy to keep it up to date, and multiple parties can collaborate to break the task of documenting a system into more manageable chucks. I also think that you should follow some sort of system when writing them. Make this part of the convention and don't stray from it unless absolutely necessary. Maybe the sections above simply become wiki pages, with subpages. Wiki markup is easy to learn for any programmer, and as long as you aren't doing anything fancy, easy to remember.

Document your processes, that's the big thing, it would be great if you have a convention, its awesome if you have some collaboration medium that let's you keep it up to date, but the most important thing is to document the process. It's been eye opening to write out a list of steps for some of the "simple" tasks I do on a project from time to time. Since its become routine in my head the task is one step, do the task, but when I write it out on paper there are 13 steps with small conditional branches. It seems easy to do a task you've done a hundred times before, but it can be maddening to someone new trying to accomplish that task without the help of the well-worn mental path you've painstakingly claimed from the jaws of chaos.

I have been on projects with great documentation, and some with not so stellar documentation, and it is like night and day. So here's a thought experiment, a trite and cliche one, but if your entire development team got hit by a bus tomorrow and some new guys had to come in and deploy, how long would it take them, could they even do it? The answer should be, they would simply bootstrap then look in deploy and follow my step by step guide to deployment success, if your answer was, they would pray and put on their detective hats, ding ding ding, you've got some documentation work to do.

first step into web design

I have degrees in Computer Science and Mathematics, this means that I'm a huge nerd, it also means that I should, under no circumstances, attempt to design things. What happens when programmers try to design graphics? Normally they come out badly, our brains just aren't wired for making things look nice. There are of course exceptions, but do a google image search for "programmer graphics" and you will find thousands of examples of terrible, terrible artwork. Here is one I found that exemplifies what I'm talking about

Scary isn't it? Well us programmers and mathematicians should be kept far far away from designing things. We also like to break the rules and in that spirit I would like to announce that my first wholly designed site is now live. It is for my friend Tim's band, Cap City Quest.

I think the design is passable, what with blueprint css and jquery plugins, these websites basically make themselves these days. Making it did reinforce a very good lesson, Do what you are good at, farm out the rest

So this was my first step into an actual public facing site design. I think I did ok, if you have suggestions feel free to leave them here. If you want me to design you a site with sweet delicious jquery and blueprint and maybe even some dynamic content, leave me a comment. This site took about 10-12 hours of work, it was a quick one off project, but I enjoyed it.

If you missed the link up above, go and view it now Cap City Quest

first step into web design

I have degrees in Computer Science and Mathematics, this means that I'm a huge nerd, it also means that I should, under no circumstances, attempt to design things. What happens when programmers try to design graphics? Normally they come out badly, our brains just aren't wired for making things look nice. There are of course exceptions, but do a google image search for "programmer graphics" and you will find thousands of examples of terrible, terrible artwork. Here is one I found that exemplifies what I'm talking about

Scary isn't it? Well us programmers and mathematicians should be kept far far away from designing things. We also like to break the rules and in that spirit I would like to announce that my first wholly designed site is now live. It is for my friend Tim's band, Cap City Quest.

I think the design is passable, what with blueprint css and jquery plugins, these websites basically make themselves these days. Making it did reinforce a very good lesson, Do what you are good at, farm out the rest

So this was my first step into an actual public facing site design. I think I did ok, if you have suggestions feel free to leave them here. If you want me to design you a site with sweet delicious jquery and blueprint and maybe even some dynamic content, leave me a comment. This site took about 10-12 hours of work, it was a quick one off project, but I enjoyed it.

If you missed the link up above, go and view it now Cap City Quest