mtrpcic.net Writing software since 1932

20Feb/131

Project, Process, Profit?

For the past several weeks, there has been a lot of discussion both online and in my office about the "ideal" practices when it comes to software development.  What steps should be taken before you start coding?  How much planning should you do?  How do you eliminated scope creep?  Around the same time we were holding these discussions at work, someone asked on Reddit.  While I was a little bit late to the game, my comment received a fair amount of traction, and even generated some direct messages with questions and comments.  I thought the ideas worked well, and decided to post them here as well.

The following are the steps that I try to follow when starting up a new project, whether it's going to be a web application, a useful library, or anything in between.

1. Basic Idea
I usually start by getting some idea stuck in my head. It'll come to me while on the train, maybe laying in bed, or while watching TV. If it's a good idea, I'll think about it a bit more, and start to think about features. At this point, it's all in my head.

2. Features and User Stories
Once I've rolled an idea around in my head for a while, it starts to evolve and get uniquely defined features. At this point, I'll start by writing the features out in a notebook somewhere (for me, hard copy helps my ideas flow better than using a computer). After a rough point-form list of features is done, I make them more details as "User Stories", which look like this:

As A User:
  I want to be able to register for an account by entering my email
  and password.

  I want to be able to post notifications and have them automatically
  be emailed to all of my subscribers

As A Subscriber:
  I want to automatically receive emails whenever one of the users
  I follow submits a notification.

You'll notice these are basically lists of "Wants". Also notice that the list is fairly fine grained, and can be quite long. Once you know what you want, you can go a step further.

3. Mockups
If my application is going to have a user interface (like a desktop or web application), I'll draw a few sketches in a notebook. I am not a designer, artist, or User Experience professional, so these sketches always look terrible and never stick, but they help me to find the rough "look and feel" that I'm going for.

If you're more technically inclined, you can get Balsamiq Mockups and create interactive mockups on the computer. I highly recommend this product.

4. Deciding on Tools
Ok, so now I know exactly what I want to build, from features to (rough) design. The next step is to decide on my toolset. I'm familiar with many different languages, libraries, and frameworks, so I sit down and do a bit of research to find the best one(s) for this project.

For example, if I'm creating a real-time, auto-updating web application, I'll do some research to find out which web servers I'm familiar with have the best support for WebSockets, and might find out that I can integrate my HTTP and WebSocket server if I use Tornado and SockJS.

5. Planning
Once the tools are decided upon, I plan the project out. I rarely need to come up with my own directory structure, as whatever framework I'm using will dictate one for me, whether it's Ruby on Rails or Django.

To start my planning, I create a new board on Trello, and give it four columns, labelled "To Do", "In Process", "To Verify", and "Done". I convert each user story from Step 2 into a task in my "To Do" list. I also add a few other tasks that relate to the general "start up" process for a project, such as setting up a Github repository, etc.

6. Development
Ok, I know what all my features are. I know what tools I will use to build the site. I know what all my tasks are. I'm ready to start. I go through the tasks in whatever order I feel makes sense (keep in mind, some tasks will require others to be completed first), and add those features to my program. When I start a task, I move it to the "In Process" list in Trello, and when I'm done it, it goes into "To Verify". It does not go in "Done"!

After about a week has passed, I'll go back to the "To Verify" task in Trello and read the user story I put together. I then try to do what it says in my application, and ensure it works. If you have two or more developers on a team, it is good practice to only verify someone elses work. The reason I wait a week is so that I "forget" some of the "quick tricks" you learn while repeatedly trying/testing during development. Being stuck in this routine while verifying can cause you to miss things.

Once a task is verified, it goes into the "Done" column. Once all tasks are in the Done column, the project is "complete". Many times, I'll do a project over multiple iterations, so this set of steps will happen once or twice, with a different starting point each time.

3Jun/121

Time to put my Top Hat on!

After just over three years of work at Fluid Media Inc, I've thrown in my hat in exchange for a new one.  Starting tomorrow, I'll be spending my days working for Top hat Monocle.  I'll be spending most of my time writing Python and JavaScript, which will be a nice change of pace from the world of Ruby I've grown accustomed to over the past several years.  I look forward to working with my new team, and I've been told that there is a Bulk Barn near the new office, so absurd quantities of candy will be had by all.

Wish me luck!

Filed under: Personal 1 Comment
24May/122

Neglect

My life is like a snowball rolling down a (very) snowy hill.  Every step of the way, it picks up something new.  I'm finding that my days are going by faster and faster, yes I've always got more and more to do.  I've got three unfinished Open Source projects I want to get out the door.  I've got work, evening classes, and a (moderately) strict running schedule as I prepare for a few Half Marathons in the fall.  In the middle of this massive snowball lies my profoundly informative blog - which has been neglected for the past few months.  Well, no more!

Rather than only making posts about finished projects, point releases to existing projects, tips and tricks, and other day-to-day happenings of my outrageously interesting life, I'll be posting the problems I'm having with my software.  I'll be posting the ideas I have for new projects, most of which will never see the light of day.  I'm going to try to be more informative with not only the technical aspect of my projects (by releasing code on Github), but to also show some of the thought process that goes into designing a piece of software with the intention of having somebody else use it.

This should be interesting...

Filed under: Personal 2 Comments
1Feb/120

DemoCamp Hamilton 5

I've been invited to speak at DemoCamp Hamilton 5, on February 9th this year.  I'll be giving a brief demo of PathJS, a client-side routing library I wrote last year.  The reason I decided to demo PathJS was because of the high abundance of web-based technology at previous DemoCamps.  Nearly every demo thus far has either been primary web-based, or had some web-based component.  The problem is that the software I've seen thus far is treating their content as "web pages" and not "web applications".  In order for the web to move forward as the base for an application environment rather than a simple series of pages, companies and organizations are going to have to start working towards m

2Jan/120

Around the Bay: 30K

I've been thinking about doing an "official" run for a while now. There are some small 5k and 10k runs in towns, suburbs, and cities nearby, but nothing I found in time that's right here at home.  Then I decided, "Who needs to 'warm up' with a 5 or 10 kilometer run?  Why not just go for broke and put my body through the meat grinder with a mean 30k?"  Then I signed up, saw the map, and immediately realized just how far 30k actually is.

While I know the masses are just frothing at the mouth to throw their money at me, I urge anyone with a few spare dollars and a few spare moments to donate to the cause instead.  Your donation will help the new St. Josephs Surgical Center, the redevelopment of their new Mental Health facility, and zombie research.

Filed under: Personal No Comments
25Jul/110

Documentation – The Nectar of the Gods

Since day one of college, documentation was toted as being of the utmost importance.  It was necessary, at all times and in every situation.  "By god, what does the variable "i" mean in this "for" loop!?" I could imagine my professors mumbling as they read through my code.  Of course, when I was writing that code, it was painfully obvious what "i" was doing.  It's always obvious what "i" is doing - isn't it?

Of course, my example above is a bit simplified, but it proves the point none the same.  No matter how complex the code that you're currently working on may seem, it's always within the realm of understandability.  Step back for several weeks, and walk into the hellish nightmare that is The Spaghetti Abyss, and you'll spend five minutes wondering, "What the hell was this fool doing?" followed by a brief flash of recollection and embarrassment - "Gasp! I am that fool!"

And therein lies the rub.

As soon as I finished my time in school, documentation seemed much less important.  You see, up until this point, students had been documenting merely to get the marks for it.  We documented our code because our grades depended on it.  As soon as I stepped out those doors for the final time, I remember thinking I was free of that nightmare.  I was a good programmer, I could look at code and understand what was happening under the hood; I didn't need an explanation.

Fast forward a couple of months, and I'm at work, trying to solve a particularly bad problem - a problem I inadvertently produced several weeks back, in a module that had since been left to stew in the bowels of a great beast of a project so terrifying, so insidious, it was Beelzebub incarnate (in code).  I open that file, thinking "This will be an easy fix - after all, I wrote it."  Never have I been more wrong in my life.  My undocumented code put a bucket over my head and slammed it with a baseball bat.  It took me several days to fix a bug that was incredibly simple, but my lack of documentation fanned the flames until my ego was burned to the ground.  I wasn't a good programmer anymore; a good programmer wouldn't have run into this problem.

Fast forward yet again.  I need to delve deep within the source code of ActiveSupport.  I'm looking at code written by the deities of code.  These men and women know Ruby from top to bottom, inside out, and to a peasant like me, it looked like they were making use of every trick in the book to get things done.  But, if that was the case, why was it so easy for me to understand everything?  Why was I able to follow along at a nice leasurely pace, instead of having my eyes melt off my face? Oh, I see now...

This code had documentation.  This code had a dictionary beside it, and I could find out what everything was doing every step of the way.  This code was easy.

It takes a situation like the one described above to let you know how important something really is.  You can be an amazing problem solver, and a prolific programmer, but you won't ever be considered one of the best until your code can be understood by thousands of people at a glance.  Now that I've got my own projects, I make sure that I do my best to document every code change.  I try to act like one of the best, because I'd like to be one of the best.

1May/111

Accents are a funny thing.

Accents are a funny thing, eh?  Being a native Canadian, I'm constantly told that I sound Canadian.  I guess that makes sense, the same way that someone can sound Texan, or someone can sound British, Irish, or Scottish.  They're all speaking English, but there's definitely something different about each and every one of them.  Whenever you speak, you don't just speak in a particular language, you most certainly have a particular accent.

This got me thinking - When I program in a particular programming language, do I also program in a particular accent? Of course I do.

There are a thousand little things we all do when programming that individually have their own names (Naming Conventions, Indentation Style, Equality Checks, etc), but when you think of them as one combined unit, they construct your individual accent.

Naming Convention

There are so many different possible naming conventions that it's nearly impossible to guarantee that a large development team will all use the same ones in the same situations:

var userName = "Mike"; // Camelcase
var UserName = "Mike" // Upper Camelcase
var strName = "Mike"; // Hungarian Notation
var user_name = "Mike"; // "Ruby" Notation
// And many, many more.

Which conventions do you use in what situations?  Do you name Modules different than Classes?  Classes different than Methods?  Methods different than variables?

Indentation Style

// Do you like to keep your braces on their own line?
function totallyBananas()
{
    alert("Bananas!");
}

// Or with method/class definitions?
function totallyBananas(){
    alert("Bananas");
}

Do your conventions differ for method definitions, class definitions, if/else statements, or other code blocks?  Do you prefer 2, 4, 6, or 8 space indents for different pieces of code?

Equality Checks

// Do you like to check that things are equal?

if(authorized == true){
    alert("Hello, Mike.");
}

// Or inequality?
if(authorized != false){
    alert("Hello, Mike.");
}

Value-First Comparison

We most often see the variable name come first when doing a comparison, but this can lead to some embarrassing mistakes...

var name = "Mike";
// We've all seen this before.
if(name == "Dave"){
    alert(name); // You should never see this!
}

// But this isn't what we meant!
if(name = "Mike"){
    alert(name); // You're going to see "Mike"!
}

Some people have taken to doing "value first" comparisons, which can avoid these mistakes.  Which way do you speak?

if("Mike" == name){
     alert(name); // You should never see this!
}

// This will throw an error.
if("Mike" = name){
    alert(name);
}

There are hundreds of other little things that make up your "programming voice".  Your documentation style, namespacing habits, source file naming conventions, and even your SCM commit messages are all little pieces of what your code sounds like.  So, is your code from the royal palace, or the Louisiana swamps?  Regardless of what your code sounds like, just make sure that your coworkers and colleagues can understand your accent.

4Jan/110

Staying Fresh

I recently took a hiatus from doing any personal software development, and for good reason as well.  Over the past month, I was feeling a little bit tired of what I was doing; starting to feel "burnt out", if you will.  This is a huge problem, because if you don't love what you do, you're in the wrong field of work.  Software Development is a constant learning process for me, and is my number one passion in life, and getting tired of it would mean losing a huge portion of what I love, and what makes me who I am.

The reason I was starting to get out was due to something that happens every day, do every developer.  Your current knowledge becomes outdated.  Working with the same technology over and over, you begin to write cookie-cutter code; code that can be duplicated time and time again.  It's no longer unique. It's no longer you.  This stems from me forgetting to do something that is fundamental to any developer on a daily, if not hourly basis.  I forgot to keep learning.  Projects that were partially completed just hung in the ether, never seeing the light of day, constantly being reassured that, "Yes, yes, I will work on you tomorrow!"

After a brief hiatus to the casual, personal programming I know and love, I've opted to do two things that will keep me learning for at least the next several years:

  • I've registered to go back to school.  I'll be heading to University as a part time student to further my credentials and learn new things
  • I've made it a goal to write one new, interesting piece of software every week.  This can be as simple as a script, or as complex as a website; the project doesn't matter.  At the end of every week, I want to be able to point to a piece of code and say, "I learned that this week."

With these two goals hanging over my shoulders, I'm diving back into the world of development with new resolution and determination.

Filed under: Personal No Comments
22Nov/103

The fine line between “Code” and “Good Code”

I've been spending a fair bit of my spare time working on my current project, and one of the major issues I'm having right now is drawing the fine line between writing code, and writing good code.

How many times have you sat down with a good, solid idea, only to sit and stare at your monitor for 30 minutes because you're trying to think of 30 different ways to accomplish the same goal. You end up asking yourself 10 different questions, each with 10 pros and 10 cons, and you wind up with a very solid understanding of what the end product will do, but you've made no progress towards it.

"Is this going to be DRY enough?"

"Should I use List Comprehensions here?"

"Should these be params to the method, or passed in when the object is initialized?"

I find myself running into this problem quite often, and always come to the same conclusion.  The conclusion that should be at the heart of as much as your logic as possible; Keep it simple, stupid.

When you're confronted with the "Mile-a-Minute Mind" scenario, just sit back and write whatever code comes to mind that gets the job done.  You're not writing good code, you're just writing code. Wow, that was easy?  It's ugly, but it was easy.  Alright, what's next?  Well, you could (and should) write any pertinent Unit Tests for the code you just wrote.  Make them as solid as you can.  Now you've got a product.

Congratulations, you fought through your own indecision, and wrote some code.

Now we're excited.  What next!?  Well, you wrote some code, and you wrote tests for your code.  Now comes the fun part.  Now you can get rid of that code, and replace it with what we've wanted all along; good code.  Thanks to our wonderful Unit Tests, you'll know if your new code is up to the same dastardly deeds as your old code.  Refactor your work of art to your hearts content, until it's as good as it can possibly be.

The moral of the story is that indecision is the bane of productivity.  Don't worry about writing concise code.  Don't worry about writing optimized code.  Just worry about writing working code, then take it from there.  As we say in the world of Test Driven Development, "Red, Green, Refactor."

3Nov/101

Starting Fresh

I've had mtrpcic.net for nearly two years now, and until today it's gone largely unmaintained, unmodified, and unloved.  After two years, I decided to take down the static HTML and put up something productive.  Interesting projects, helpful tips, and answers to hard problems will be shoved into the confines of this blog with the intention of giving back to the community that's helped me get to where I am today.  Without any further ado; a brief introduction:

The Work

I am a Software Developer located in Southern Ontario specializing in Web Applications and Business Solutions.  I've been working in a professional capacity for over 2 years, and have worked extensively with both PHP and Ruby on Rails (as well as with the appropriate client side libraries like jQuery and ExtJS).  I am currently employed at Fluid Media Inc. where I build Web Applications to help make peoples lives easier.

The Play

Having been an avid gamer for over 17 years, I spend a fair bit of time in various virtual worlds.  I'm currently suffering a severe addiction to Minecraft, but find time to break away and combat alien races in Starcraft or fight off terrorism in Modern Warfare.  Gaming is a particular passion of mine that I'll never have enough time for, but will try to fit it in whenever possible.

The In Between

When not engrossed in work and play, I like to spend my time enjoying books and (very few) television shows.  I often spend available time researching new and developing web technologies, while trying to conjure up real world applications for them.

Filed under: Personal 1 Comment