Copyrights Conundrum

by: micah | March 12th, 2009 | 2 comments »

Here’s the situation. You’ve spent days working on an open source project. Your sweat, blood, and tears have been poured into thousands of lines of code spread through countless file in a sprawling tree of directories. The final step is to release your masterpiece into the wild. So you choose your open source license and then it hits you; you realize that need to add a copyright header to EACH and EVERY source code files. How tedious! You google for a tool that will automatically add the headers for you, and you find nothing satisfactory. In the end, you write your own script to add the headers for you.

I’ve been in this exact situation and written such a script too many times. My most recent experience and script implementation will be the last. I’ve dubbed this last imeplementation MM Copyrights and you’re welcome to use it.

MM Copyrights is a simple Ruby gem that will search a directory for source code files, inserting or updating a header comment in each file.

Installing

It’s just a matter of installing the gem hosted on Github.

Usage

Let’s say you want to add the following copyright header to all .rb files in the lib directory…

And all the ruby files will look like this:

Typically I keep the copyright text in a separate file and write the following Rake task…

or the following ant task if need be…

Details

If you haven’t guessed, MM::Copyrights::process takes 4 parameters.

1. The path of the directory containing source code.
2. The extension of source file to be processed.
3. The comment prefix. Note that there’s an extra -. This is because we want the copyright comments to be unique from all other comments. The tool will search for this unique prefix to find existing copyright headers.
4. The copyright text, without the comment prefix.

That’s about it. Feel free to run MM::Copyrights::process multiple times on the same code base. It’s harmless. And when the new year rolls around, just change the copyright text and rerun the tool. It will update existing headers.

Kata: Langston's Ant in Ruby

by: micah | November 13th, 2008 | 3 comments »

Langston’s Ant in Ruby Kata Screencast

I’ve recorded my Langston’s Ant kata for all to see.

This particular kata, with slight variations, has been in front of an audience twice before. Once at a Software Craftsmanship group SCG meeting and again at RubyConf2007.

On both occasions I asked the audience to evaluate my performance on a scale of 0-10, 0 being the worst kata you can imagine, and 10 being the best. At the SCG, my performance was longer than the screencast because I didn’t use the instance_eval trick and wrote multiple case/when statements. It resulted in much more code as well. Honestly, I felt the kata dragged on a bit too long which is why I shortened in subsequent performances. Despite this, the SCG audience gave me an average score of 8. At RubyConf, the kata was almost exactly like the screencast and it earned me an average score of 7.

Now coming from an audience of dedicated Ruby developers, I’m quite pleased with my score. Here’s some of the feedback I got…

• Use of instance_eval: -1
• First test, going from compile error to passing tests: -1
• Refactoring on with red bar: -1 (not repeated in the screencast)
• Non-idiomatic is_black?: -0.5 (fixed in screencast)
• Steps are too big in between tests: -1
• …

I find this feedback immensely valuable and thank those who took the time to provide me with it.

In martial arts, the techniques performed in kata are not always by the book. There is an aspect of art, creativity, and entertainment. At several points in my Langston’s Ant kata I intentionally decided to bend the rules to enhance artistic and entertainment values. I leave it up to you whether I made the right compromise or not.

After watching the kata, leave a comment with your rating and any feedback you have for me. I thank you in advanced.

Simon

by: micah | November 10th, 2008 | 0 comments »

You remember the classic Simon game, right? The one where the electronic devise will blink a color and make a sound that you have to replicate by pushing the colored buttons.

At RubyConf 2008, I cornered Jim Weirich and asked his opinion on Limelight. He didn’t feel like he had seen enough of it to give a good opinion. So we found an hour where we could both sit down and build a simple Limelight production. We decided to build Simon.

The result is really quite simple. It’s a couple hundred lines of code, UI, game logic, and all. It’s also got a suite of unit tests.

If Limelight is installed, you can download the production file, and double click it, or enter the url in the Startup Limelight Production.

Limelight Production file: http://blog.8thlight.com/files/simon.llp

The Source Code can be found on github.

Ruby Battleship Sparring Tournament

by: micah | November 8th, 2008 | 0 comments »

Yesterday in my talk at RubyConf2008, I announced the commencement of the Ruby Battleship Sparring Tournament.

This is an open tournament. All are welcome to participate.

Limelight 0.3.0 Released

by: micah | November 5th, 2008 | 0 comments »

This release of limelight contains many new features and stability. Perhaps most notably, Limelight will no longer eat 95% of your CPU (ouch)! It's proud to say it's becoming quite usable for real apps of considerable size.

Default event implementation - feature_request
Image player - feature_request
Sending variables to partials - feature_request
CPU Hog -
Gems in productions - feature_request
Giving Floats to prop styles - feature_request
Scene's Default name - feature_request
Hand Cursor Stays - bug
generate production templates - feature_request
Validate styles - feature_request
Auto resizing doesn't trigger update on parent. - bug
Double click to open production - feature_request
Color as a hash - feature_request
Add more Known colors - feature_request
Need to relaunch when changing player. - feature_request
Shared Players - feature_request
Unique IDs - bug
Building a Production - documentation
Document Events - documentation
Document Prop API - documentation
Document Styles - documentation
Variable size text areas - feature_request
Editable TextArea size - bug
Simple App screencast - documentation
RDoc - documentation
finish 0.2.0 release - release
Reserved prop keywords - bug

Agile in Buenos Aires

by: micah | October 29th, 2008 | 0 comments »

Fidelity Life Case Study

by: micah | October 2nd, 2008 | 0 comments »

Software Craftsmanship Group

by: micah | October 2nd, 2008 | 0 comments »

Definition of Software Craftsman

by: micah | September 21st, 2008 | 5 comments »

Craftsman Clarification

There has been some discrepancy in the use of the term “software craftsman”. Rather than going into details about various uses of the term, I’ll just clarify what I believe it means.

software craftsman n. A man who practices the software craft.

There are a few points to make about this definition.

1. “software craft”

A craftsman believes that software is a craft. This is important because not everyone believes this. A craftsman takes pride in his work an strives to do the best job he can. He believes that writing good software requires skill and careful attention. That software is not something that can be manufactured nor can it be delivered faster by merely adding more bodies.

2. “practices”

A craftsman practices his craft, always striving to become more skillful, to produce better software.

There are traditionally 3 stages of craftsmanship:

1. Apprentice
2. Journeyman
3. Master

No matter which stage one may be in, as long as he practices software as a craft, he is a craftsman.

3. “A man”

Technically the term “craftsman” is gender specific. Women are just as capable of software craftsmanship. Indeed, I’d like to see more software craftswomen out there. In an effort not to alienate anyone we should use the term “software craftsperson” more liberally.

Update: There’s a movement afoot to make the term “software craftsman” gender neutral. Feel free to comment below.

I’ve checked with the book “Software Craftsmanship” by Pete McBreen to see if it conflicts with my definition. Although, he uses the term “software craftsman” ambiguously at times, he is careful to use the term “master craftsman” when referring to craftsmen at the height of his craft. This is in line with my definition.

I hope this serves as a reference for my use of the term. People should not think me presumptuous when I call myself or my colleagues craftsmen. I mean only what I describe above.

Tag! I'm it!

by: micah | July 2nd, 2008 | 2 comments »

David Chelimsky tagged me with this “chain-blog”. I’ve enjoyed reading other peoples’ stories. Here’s mine.

How old were you when you started programming.

Hard to say. I suppose I was legitimately writing code at 9 years old

How did you get started programming.

You might say I was born into programming. At a very young age, maybe 4 years old, my dad (Unclebob) would put me on his shoulders and take on a robot’s personality. He would remain motionless until I ordered a command. For example, if I said “walk” he would start walking. If I said “turn” he would turn. And in a very computer-like-fashion, he would follow my orders to the “T”. After a “walk” command, my dad would not stop walking until I issued a “stop” command. Poor programming on my behalf often led my dad, with me on his shoulders, straight into a wall. I used to laugh with delight as he’d bounce off and walk into the wall again and again until I corrected my programming error.

What was your first language?

At 9 years old my dad taught me Logo. I was drawing circles, squares, spirals, and in general making that turtle dizzy.

What was the first real program you wrote?

In high school I programmed casino games on my TI-81 during physics class. You could play Black Jack, Roulette, Bet on the Horses, play the One Armed Bandit. My friend Jim Maggio even did some pixel art for the slot machine. It was pretty sweet. All the physics students were required to have TI-81’s so my games ended up getting copied over and over. My first open source experience I suppose.

What languages have you used since you started programming?

In chronological order…

Logo, Basic, Fortran, Pascal, Forth, C, C++, Scheme, Java, Python, Ruby, JavaScript, C#, Objective-C, Smalltalk, Assembly.

Whoa! I’m impressing myself with that list. But who am I kidding? I doubt I could remember how to write HelloWorld in half those languages now.

What was your first professional programming gig?

An internship at Object Mentor. I wrote some Java Servlets to automate parts of their website.

If there is one thing you learned along the way that you would tell new developers, what would it be?

Software is not a spectator sport. ie. Just watching people code won’t make you a good coder. Code as much as possible if you want to master your craft. Code at work. Code at home. Code on vacation (WARNING Your spouse may throw your computer off the balcony). Code for fun. Code to kill time. Code while you’re sleeping (I mean in your dreams).

What’s the most fun you’ve ever had programming?

The project the David Chelimsky referred to was mighty fun. But I’d have to say the most fun I’ve had with my colleagues at 8th Light, Paul Pagel, Jim Suchy, Eric Smith, and Doug Bradbury. I have never worked with a stronger team. When it comes to software, I imagine we could prevail over any challenge. Outside of software, our strengths are less impressive….

1. We started a basketball league and had a perfect record: 0-10. That’s right, we lost 10 out of 10 games.
2. We went on a ski trip together an managed to loose some family members in the mountains, during a snowstorm, at night. They lived.
3. Doing push ups every hour of every working day surely made us stronger and earned us an infamous reputation in the office.

Up Next

Paul Pagel, Jim Suchy, Eric Smith, Doug Bradbury, Matt Segvich, Unclebob, Bob Koss, Michael Feathers, Dean Wampler, Tim Ottinger, Chad Fowler, Jake Scruggs, Mike Clark, James Grenning

Tag! You’re it!

Announcing Limelight

by: micah | June 2nd, 2008 | 1 comments »

I’m pleased to announce the open source Limelight project: A thin client and application framework written in Ruby (JRuby).

http://limelight.8thlight.com

LimeLight at RailsConf 2008

by: micah | February 4th, 2008 | 4 comments »

Back at RubyConf 2007 I prepared a 1 minute presentation, well… more of a teaser, about an application framework called LimeLight.

What is it? LimeLight is a selfish dream of mine. In a nutshell it’s a light weight ruby framework for building rich client applications. To explain further, know this. I hate building web applications. Not because they’re hard to build or anything silly like that. It’s because they’re so perverted. Writing web apps makes me feel dirty; as though I’ve sunk into a pit of waste and decay where the foundation of my work is a pool of sludge. No matter how hard I may try, the very nature of modern web apps taints my code and leaves me a sour, grumpy developer.

To understand what I mean, consider the trivial little widget on the right here. Try clicking the button and watch the light blink. Simple huh? Can you count the number of languages/technologies used in implementing this widget? And don’t forget the code required on the server side…..

I count 5. That is, in most cases this widget would require about 5 or more different languages. Let’s count. HTML of course. CSS to make it look right. JavaScript. That’s 3, but in most cases you’ve got server-side code which, if you’re lucky, involves Ruby and ERB. Think about it. You need to know 5 difference languages to build that silly widget. Yikes!

I’ll include the code below. Know that I’ve made every effort to make this code as clean and simple as possible. Still, I would need to borrow your hands and feet to count all the things I find distasteful about it. Have a close look. Ask yourself, “Couldn’t there be an easier way to do this?” I say there is.

If you’d like to learn more, I’ll be presenting on the topic at RailsConf 2008. Or you can come back this this blog site later. I’ll be sure to post any exciting progress.

    

        Stop
    
    
    

Micah's General Guidelines on Ruby require

by: micah | October 8th, 2007 | 12 comments »

Ruby files have to require other files. There’s not avoiding it. Techniques to manage require statements are numerous and varied. Having tried most of them, I’ve found a system that works well for me. What follows are the guidelines I use to manage Ruby require statements.

1. Establish a Convenient Search Path

Although it’s possible to use absolute paths or complex relative paths such as below,

this should be avoided as much as possible. Otherwise you’ll be fixing dozens of require statements every time you move a file. It’s no fun. You’ll want your requires to look like this:

To achieve this, add your lib directory to the ruby search path.

$: << File.expand_path(File.dirname(FILE) + “/../lib”))

This will have to go in one of the first files that gets loaded. If you’ve got a standalone Ruby app, you could add this to the startup script. In a Rails app, it can go in environment.rb. If you’re using RSpec, you may want to add it to spec_helper.rb.

2. Independent Requiring over Require Farms

In some projects, you’ll find files that contain nothing but require statements. It’s common in gem projects. The advantage is that users of the library need only require one file which in turn requires everything else you’ll need. Convenient huh? Sure is. But there are 2 major consequences of this:

1. Maintenance Mayhem - Every time you add, delete, or rename a file you have to remember to update the require farm file. It’s easy to forget. And the order of requires can get very hard to manage especially if you end up with cyclic dependancies.
2. Drowning in Dependancies - Require Farms have a tendency to require more than you want. If there’s only a portion of the library you’d like to use, with the Require Farm you get the whole thing. The extra dependancies will consume more memory at run time and they may add undesired behavior to your system. In general, this is a violation of the Dependancy Inversion Principle.

Rather than build Require Farms, allow each file to be responsible for it’s own dependancies. Let each file require the files it needs to work. This approach can be a bit annoying as you’ll find your self using altogether more require statements, but it’ll pay off in the long run. With each file independently managing it’s dependancies, the system will be easier to maintain and it’s components more reusable.

3. Building Absolute Paths

Try as you may, you can’t always avoid using absolute file paths in your require statements. The following is reliable way to refer to other files.

Let me break it down. First:

This gives you the directory of the current file that is being executed. However, you never know what you’re gonna get since the form of the path is based on how the program was executed. This might give you an absolute path or it might give you a relative path from anywhere on the system. In some cases, Ruby won’t do what you expect with relative paths so it’s best to expand this into an absolute path.

Now you’ve got an absolute file path and you just have to add a relative path to the desired file. Normally I’d do this:

However, this is not quite portable since I’m using forward slashes. To get this to work on any system independent of file separator, use File.join as shown above. Use this technique to require files when you don’t have your search path configured.

Happy Requiring!

Ruby DSL Blocks

by: micah | May 20th, 2007 | 4 comments »

There’s a common pattern I’ve seen for developing DSLs (Domain Specific Language) in Ruby. It’s used in RSpec, the Statemachine Gem, and Unclebob’s Clean Code talk at RailsConf 2007. I haven’t seen a name for this pattern so I’ll call it the DSL Block Pattern.

RSpec

Statemachine

Parser

Here’s the problem. You’ve got to write code for specific domain such as writing specifications (RSpec), defining a Statemachine, or defining command line arguments (Unclebob’s Clean Code talk). These domains have a contained and well defined terminology set. Often the cleanest, most elegant way to express this code is to create a DSL.

Before diving into the example, let me say that I like coffee as much as the next guy. But I feel lost when ever I go to a Starbucks. As you know, Starbucks has a it’s own language, DSL if you will, for ordering coffee. What follows is a DSL Block for ordering Starbucks coffee.

The general grammar for ordering coffee is: Size, Adjective (optional), Type of Coffee. This is by no means comprehensive but it’s sufficient for the example. So if you wanted to order a large coffee, for example, you would say, Grande Coffee. A small espresso: Short Americano. An extra large mixture of regular and decaffeinated coffee with some half and half: Venti Breve Half Caff.

Given the task to code these coffee orders, I’d like to be able to code it like this:

Ok that looks good, but as you look closely, you’ll start to wonder about those methods, grande, short, and venti “Do they have to be defined on the Kernel?” you may ask. Defining them on the Kernel is a scary prospect. And that may convince you to clutter the syntax by passing an object into the block like this:

This would allow you to define the grande, short, and venti methods on the object passed into the block. Although you do need an object where grande, short, and venti will be defined, you don’t need to add an argument to the block. You’ll find code out there, such as Migrations, that uses this less optimal route. It’s not necessary. The trick to get rid of the argument is below:

You can see that the Order object is doing all the work. It’s got the responsibility of interpreting the DSL, so let’s call it the Interpreter Object. The Module::order method simply creates an instance of Order and calls istance_eval on it. This causes the block to execute using the binding of the Order instance. All of the methods on Order will be accessible to the block.

The Interpreter Object can do any number of things as it interprets the DSL. In this case it simply generates a translation for Starbucks newbies. But, the sky’s the limit really.

Show all the source code.

Chirb Statemachine Talk

by: micah | May 8th, 2007 | 1 comments »

Last night I presented the Ruby Statemachine Gem to the Chicago Ruby Users Group (Chirb) Below are links to download the slides and coding example used.

Finite State Machines and the Statemachine Ruby Gem (Slides):

• statemachines_chirb0407.pdf

Statemachine Exercises:

• statemachine_exercise.zip
• parser_spec.rb - Additional specs contributed by Michael Buselli