Code Softly

Comment Gadget Fail

2010-03-10T20:08:57Z

I’ve switched back from the Google Friend Connect comment Gadget to the original Disqus comment setup.

Why I Wanted Friend Connect

I love the idea of readers “joining” Code Softly, much like they might follow a site on Blogger. So I added Friend Connect’s members gadget to the sidebar (you should totally join).

Once that was in, I found the recommendation widget, which was kind of a nice and generic thumbs-up gizmo, kinda like digg or reddit .

So far, so good. You can join the community and then flag posts you like.

Then I thought it would be cool if people could comment using the same identity they created when joining and recommending. That’s when things got rocky.

Where the Comment Gadget Falls Down

I was happy to see the commenting gadget in the Friend Connect gallery. I yanked the code for that sucker, tweaked it a bit, and punched it onto the site.

I immediately saw a few problems:

No aggregation. There was no easy way to indicate on the homepage how many comments a post had. I got around this by showing a collapsed widget at the bottom of a post, but it still felt kinda awkward.
No formatting. Comments get all of their formatting removed. Things like whitespace are important for aesthetics, especially when people might be posting code snippets and stuff.
Strange comment counting. A reply to a comment isn’t “counted” as a comment. For example, if Lenny makes a comment, then Carl replies to Lenny, the total comment count is one.
No easy view of all the comments on the site.

With My Tail Between My Legs

After a few posts, I realized that feedback and discussion was suffering because of the limitations of the widget. Plus, the folks at Disqus had made some speed improvements.

So I put the older, richer, and yes better comments up. Maybe someday the Friend Connect widget will be improved upon, or someone can refute all my criticisms and I’ll be able to try it again. For now I’m sticking with what works.

What Makes Veteran Programmers Better Than Rookies?

2010-03-09T12:00:00Z

What makes an 11-year veteran programmer better than a hotshot n00b right out of school?

I think it’s fair to say that experienced programmers are better than rookies. Sure, there are exceptions, but in my time in the business I’ve rarely seen someone with a couple of years under their belt do better at creating good stuff on time than someone who’s been at it for a decade.

Before everyone goes nuts, let me qualify this a bit. I define “better” as “better able to deliver working software within a mid-size shop”. This narrows things down, but it’s where my experiences lie, so I choose to focus on it.

I have my own thoughts on why I think this is true, but I’m very interested in hearing what others have to say.

So, thoughts?

Investing In Pain: Invisible Technical Debt

2010-03-05T02:56:36Z

All too often we slap together solutions in the name of finishing on time. This has been described as incurring technical debt:

Just as a business incurs some debt to take advantage of a market opportunity developers may incur technical debt to hit an important deadline.

I think programmers intuitively feel this is correct. Good ones learn where the cutoff is, bad ones either create piles of technical debt, or paralyze their shop in the quest for gold-plated code.

One of the insidious things about technical debt is that eliminating it is more complex than just paying of financial debt + interest. There’s a psychological component that can sometimes hide the debt entirely.

For example, in a rush, Flavio crams in a complex but crude workaround to a problem. His solution gets the job done, but it’s complexity hides the fact that he has broken the object model and implemented a really crummy design.

Over time, this kludge is mistaken for “the way we do it” by other developer who come across the design. They reinforce it by building upon it, oblivious to it’s rotten nature.

When Flavio peeks back in and sees the horrible mess built upon his once-tactical hack, he runs for the hills. The technical debt has ballooned into some kind of sick nerd reverse-mortgage crisis.

Normal debts have creditors who are very good at informing their debtors of exactly how much is owed. Software doesn’t extend us that courtesy.

We’re kind of on the hook for keeping track of our own technical debt, which means we need to be disciplined and pay things off as soon as possible.

The Law of Medium Software Projects

2010-03-02T04:55:25Z

Your project probably isn’t epic, nor is it trivial. That’s precisely why it’s hard.

John D. Cook summarizes the mathematical “law of medium numbers”. In short: the hard stuff is in the middle.

Atoms are simple, and so are stars, but medium-sized things like birds are complicated. Medium-sized systems are where you see chaos.

With minimal effort, I humbly restate this as The Law Of Medium Software Projects:

For medium-sized software projects, we can expect that large fluctuations, irregularities, and discrepancies in time and effort will occur more or less regularly.

When you start from scratch with a small problem space, like “I want a portfolio site”, the solution is pretty clear-cut: Pick a basic publishing platform, get your images, prose, then organize and launch.

Super-large efforts can also be simple. If you’re building out a titanic data center, the question of “how much power we gonna’ need?” boils down to square-footage and math.

It’s the middle-sized stuff that is tricky: the four-month project, the 300-user web app, the blog that gets enough traffic to create non-trivial hosting costs, the database that’s big enough to need DBA’s, but not big enough for bleeding-edge storage stuff.

The normal curve tells us that most projects fall in the middle. The realities of our profession dictate the same.

If a job is so small as to be trivially simple, people rig it themselves or unload it to a third party provider.

If a project is titanic in scope and size, then we staff a lot of people and plan for a lot of time. While the details can be gnarly and intricate, the 10,000 foot-view of the project boils down to predicting person-hours and hardware costs.

What the Law Means to You

We need to be careful which methodologies and anecdotes we latch onto. Just because Google leans on Bigtable doesn’t mean it’s time to drop Oracle like a bad habit. Just because 37Signals says “simple is best” doesn’t mean you can ignore 95% of the feature requests from your department.

The trick is to map these successes onto our own situation. Think of it like the breakfast buffet at Denny’s. Sure, they’ve got cantaloupe, but you want eggs and pancakes, so admire the melon. Appreciate what it can lend to breakfast. Maybe even take a teeny piece, but don’t dump what you’ve accumulated just to make room for honeydew.

Humane HTML Tag Wraps?

2010-02-26T11:25:50Z

Every now and then I find myself writing HTML by hand. Sometimes the tags have lots of attributes, or they have long values. This makes them way longer than the aesthetic 80-ish character max. What’s the best way to wrap them?

If I start with:

<a href="http://codesoftly.com" id="awesome-link-one" class="link main" rel="bookmark">mylink</a>

What’s the best way to wrap it?

Stacked: Everything on Its Own Line?

<a href="http://codesoftly.com" 
     id="awesome-link-one" 
     class="link main" 
     rel="bookmark">mylink</a>

I like this because it’s clear what all the attributes are. There’s little chance of missing one because it’s way off the right of the screen.

I don’t like that it hides what the link text is.

One Long Opening Tag With Linked Text Indented?

<a href="http://codesoftly.com" id="awesome-link-one" class="link main" rel="bookmark">
    mylink
</a>

I like this because it leaves the link text clear and on a line by itself. It’s crummy because that first line can get really long.

Something In Between?

<a href="http://codesoftly.com" id="awesome-link-one" 
     class="link main" rel="bookmark">mylink</a>

I’m not sure this is any better. It feels like the worst of both worlds.

Oh, and “How Dreamweaver does it” isn’t a legitimate answer.

The Database Is a Time Bomb

2010-02-24T16:59:49Z

I’ve been a proponent of Movable Type as a publishing platform for a while now. I stick with it for one big reason: it is absolutely great at static publishing.

I realize that Wordpress and the gang have all kinds of neato features, fancy themes, and powerful plugins. Despite all that, I find the reliability of good old-fashioned HTML pages comforting. Even commodity hosting plans have that part figured out.

Not needing a database connection means that if the host’s database dies, my site is fine. It means that if for some unfathomable reason Code Softly gets Digg-bombed I don’t need to worry about blowing away connection pools or overwhelming my page logic.

The fact is that most sites, especially blogs, have no business being written with dynamic pages in PHP or .NET or Perl, and they certainly don’t need a connected realtime database.

Not sure if you can benefit from static publishing? Take this short survey:

Does your site change depending on which user views it?
Are you sure about that?

Bottom line, most fancy stuff is unnecessary or can be accomplished with javascript.

Think about it, what’s the most fragile piece of your website, the part that breaks the most often? (hint: it’s probably the database) The database can be mis-configured, run out of juice, or just fail to start. Tell me you’ve never had a host accidentally have a DB outage.

What’s the part of your infrastructure that’s the last thing to fail? (hint: it’s the http server, aka Apache) Why tie the fate of your site to the most fragile part of your stack, especially when you don’t really need it?

Take a look at your site. I’ll bet you can get by with a bunch of static pages.

5 Foolproof Job Fair Tips For Web Programmers

2010-02-23T04:55:29Z

I’ve just had my first experience manning a booth at a career fair. Now that I have gained only passing wisdom around this event, I choose to dispense concrete tips with guaranteed results:

You Don’t Have to Dress Up, Just Don’t Dress Down

The suit and tie looks sharp, but isn’t really necessary. A job fair is busy, kind of loud, and full of people. Most important is that you look (and smell) clean. You’re not going to win any beauty contest, but you don’t want employers to think you’re a slob.

Your Department’s Home Page Doesn’t Really Count

I usually ask prospectives “What experience have you had working with websites?” The answer an alarmingly high number of times is “I help maintain my department’s home page”.

I realize that not everyone has the opportunity to work at Amazon or CNN.com, but at least come back with something. Even running a personal blog involves at least a few principles of sound web programming.

Be Specific About What You Know

Don’t walk up and say “sooooo…what have you got?”. This is a dumb question, In this economy, you already know the answer is “not much”. Introduce yourself with “Hello, I’m Flavio. I’m studying linear algebra and am interested in a full-time programming job.” This helps the person zero in on how good a fit you might be. The people at the booth might be looking for linear algebra specialists, but when you only give them a general inquiry, they have little chance of learning that you’re a perfect match.

You Need Them More Than They Need You

If you’re participating in this cattle-call, chances are you’re not sweet enough to have attitude. Remember the part about there not being enough jobs to go around? You don’t need to approach on your knees, but don’t act offended if there isn’t anything for you. Just keep moving.

Have a Conversation

The point of the Job fair is human interaction. You could learn everything about an employer and position online and submit your resume there. You’re at the fair to stand out and maybe get an interview or job on the spot, thereby beating out all the digital posers. To do that you need to make your interaction unique but not flashy. Just having a detailed conversation will do that.

A quick fly-by to drop off your resume then pick up pamphlets and swag doesn’t do the trick. Do that and prepare to become a part of The PIle. Seize the opportunity to meet people face to face. Otherwise just apply online and save everyone the trouble.

Content Rules

2010-02-18T12:07:28Z

I’m always trying to impress upon people that more than anything else, their sites need content. It’s fun and sexy to harp on visual and design things, but at the end of the day, people won’t use your pages because they look nice. They use them because they contain some information the reader wants, be it text, images, or a neato flash game (my best distance is 321,492 feet. Deal with it).

Boagworld has a post that reinforces this nicely, putting emphasis on having a good copywriter:

Copywriters also tend to know how to spell and, vitally, how to use grammar properly. If you’re a designer and you doodled through English lessons at school, you should do all you can to catch up on your grammar and spelling. A miss-placed apostrophe or hyphen could change the entire meaning of your piece. At which point you’ve failed as a designer.

Content Is King [Boagworld]

Backlog for My Brain

2010-02-17T12:00:32Z

I recently started keeping a small notebook (graph-paper) to the left of my keyboard when I write code. It’s a short list of what I want to accomplish during a session, maybe for the next half-hour or pomadoro or whatever. I lovingly call it my analog burn-down chart.

It works great. I use it to:

Record sins I commit in the name of un-breaking tests
Jot down micro-goals; things I want to accomplish before I step away from the computer. This really helps focus me. It’s especially handy for tasks I don’t like doing or that I suck at. Javascript fits both criteria nicely.
Force myself to do things I find distasteful, like verifying javascript in IE 6.

Here’s what I had down on a recent page:

But That’s Just a To-Do List!

Yes. My analog burndown could be called a to-do list, but for me it’s a “to do right NOW” list. It keeps me focused on the task, and I know when I’m done because the list is all crossed off. I rarely go back and look at previous pages. They’re either cleared entirely, or repeated on the next list. Sort of a mini backlog for my brain.

Death to Code Review Meetings! Use Review Board

2010-02-16T12:30:06Z

This code review is dreadful. Putting it on the project schedule sure felt good at the time, but now that we’re all sitting here, I’m not so sure.

What difference does it make? The deadline is tomorrow. It’s not like this guy’s going to rewrite his entire system because it fails the review. Come to think of it, how do we even know if it fails the review? Is there a final vote to decide if it stays on the island? Does it take a simple majority? Super-majority? Can we filibuster? Whatever.

Let’s just get through this. Thaaats it…Everyone keep your heads down and your mouths shut. Let this guy finish reading every line of his code so we can get the hell back to whipping our wounded project into some kind of shape before the deadline.

Jesus, that guy just pointed out a line-break formatting issue. I wonder if I can strangle him with the phone cord from here.

I have no clue where we are now. That code doesn’t even make sense. NO, I didn’t read every line of it before this meeting. Busy coding my own stuff, remember?

Thank GOD we only scheduled this thing for one hour. I couldn’t take any more. Besides, I seriously doubt he’s going to take all that half-assed feedback and try to fold it into his code after we deliver to QA and before he starts on his next high-pressure task. Awesome use of everyone’s time.

While you may not experience all this in your code reviews, I’ll bet you’ve felt some of this pain. Code review meetings are the worst. They eat time, are poorly attended, and people are bad at preparing for them. Further, there’s generally no good pattern in place for actually implementing the outputs of the meeting.

Review Board is an awesome web-based tool that helps solve a lot of those shortcomings. It turns the review from a monolithic death march to a conversation among programmers. There’s very little pressure. You request peoples’ eyeballs, they weigh in, you update, rinse, and repeat.

Review Board will not blow your process to hell. It’s a very generic tool. If you have more than one person writing code, Review Board will be useful.

Think of it like a message board centered around a code diff. One person posts a diff, the “subject” of the thread, emails go out to other programmers who can look at the diff and have threaded conversations around it.

To learn more about Review Board, visit their homepage and get started. For the visually inclined, check out their screenshots of the app in action.

Python Flame-bait or Food For Thought?

2010-02-13T00:00:13Z

Stumbled across this open letter to Python, written by Luke Magill. In it he goes through some of the ways Python has let him down, including

No Encapsulation
Static Libraries
Lack of an implied “this”
No explicit support for member definition
On-lined Lambdas

A few parts resonated with me, especially the when he talks about how Python does objects.

But you weren’t ecstatic about objects. You didn’t really like them and you didn’t trust them. So you decided to only give them a little. You cut corners. You made objects but you made them hard to use. That was a mistake.

As a former Java programmer myself, I’ll admit I’ve felt some of this pain. Not enough that it stops me from getting things done, but there have been times I’ve scratched my head over how different Pyhton objects really are from their counterparts in other languages.

Anyway, the comments make for good reading, rife with handy links. If nothing else the whole thing is a good thought-exercise.

Do Tech Stories Belong in the Backlog?

2010-02-12T01:36:24Z

I’m a huge fan of always seasoning iterations with a couple of technical stories. It’s great for closing the feedback loop and empowers developers to improve the way they deliver products.

Jack Milunsky discusses the pro’s and cons of putting technical stories in the product backlog.

But what about the type of story asked by one of the members “As a development team member, I want the existing unit tests to run under CruiseControl, so that I know if anything breaks”. Where does this belong? Well this is a perfectly written story but the story really has no ultimate value for the end user at least not directly.

I personally feel that if you don’t have some official place to put these kinds of improvements, they will always get shoved aside in the name of “real features”. Maybe adding them to the official backlog sows confusion and strife, but trying to sneak them into task estimates or something seems just as dangerous, because they’re effectively invisible and untracked.

via Technical stories - are they included on the backlog? [AgileSoftwareDevelopment.com]

Repent! Automated Web Testing is Inevitable

2010-02-11T04:58:00Z

Our job as web developers is to build defect-free sites. That job is getting harder. As sites become ~~bloated~~ more feature-rich, verifying everything in multiple browsers before it goes to QA becomes impossible. The only way to keep afloat is to allow automated web testing frameworks shoulder the burden.

Test EVERY Browser Your Site Supports

Yes, the line between tester and developer is blurring. The fact is that you really can’t call something “done” if you haven’t verified it yourself first. That means checking all the browsers your site claims to support, even the dinky ones.

“But my job is to build, not test!”, shouts the programmer. “My job is to verify, not to sniff out all browser compatibility issues you were too lazy to handle”, replies the tester.

It’s a balancing act, and as professionals we need to commit to delivering verified code. In the end, there are more feature and browser combinations than any developer could possibly check in a reasonable amount of time.

Sign In - 1990s Style

Back in the day, sites were still pretty simple, especially the trusty sign-in form.

About as simple as it gets. A couple of fields and a button and maybe a blink tag or two.

If we count features, that’s:

Show the form
Submit form
Show the welcome page or redisplay the form with an error message.

You’d probably test it out in IE and Netscape, so that’s three items to check in two browsers. You need six human operations to verify the login page. Pretty manageable to do each time you update the site.

Fast forward to the present, and things get a little more involved.

Sign In - 2010

Today’s login screens are fancy compared to their predecessors. They have javascript validation, fancy tooltips, and other fun stuff:

Counting features on this hypothetical page:

Show the form
“forgot password” link
validate input as they’re entered
show styled error messages for invalid input before submission
a “remember me” checkbox
submit form
Show the welcome page or redisplay the form with an error message.

That’s almost triple the features for the simple login page. Now testing this is more involved, especially since you’re checking it in mulitple versions of a browser:

IE 6
IE 7
IE 8
Firefox 2
Firefox 3
Firefix 3.5
Safari 3
Safari 4

So that’s 7 features over 8 browsers, or 56 verifications. That’s a lot to cover when you’re just trying to get out a damn release (If you’re uncomfortable with IE6 in there, feel free to swap in Chrome).

The login screen is likely one of the least complex pages of your site. If you can’t manage that simple scenario, you’ve got zero chance on the fancier pages.

At this point one option is to give up and leave it to QA staff to hunt down all the browser-compatibility issues. Weak. Totally weak. We’re supposed to be awesome developers. It does little for our reputation when we intentionally pass off unfinished work as “dev complete”.

The other option is to find a way to speed up the testing of the different combinations, so that we’re confident that the delivered site functions across all supported browsers.

Let the Machines Do The Work

Automated browser testing systems to the rescue. These things continuously verify your features. It’s like legalized slave labor. The machine will never get bored or tired. It doesn’t skip test to get out early on a Friday afternoon. It will happily check and recheck your pages all day, even weekends.

This doesn’t mean it’s easy. Setting up good browser tests takes time, and the curve is steep. You may start out with only a handful, like “does the homepage show up?”, or “can users sign in?”. As time goes on, you can create more sophisticated tests until you’ve got a well-oiled verification machine going.

I’ve found that the old 80/20 rule really kicks in here. With only a few tests, you can find and fix tons of problems before they get into the test cycle.

You Have Options

There are plenty of automated browser testing getups out there. I’ve had experience with Selenium. There’s also Windmill (Python), Watir (Ruby), and HtmlUnit (Java).

Pick one and try it out. I’ve found that they’re easier to get running than you might think, and the payoff is awesome, plus it’s fun to sit back and watch a magical browser window fire up and click away. Kind of a Sorcerer’s Apprentice thing (just without all the ensuing mayhem).

(mushroom cloud photo courtesy of giginger, some rights reserved ).

Scrum's Devil's Advocate: Uncle Bob

2010-02-09T13:08:56Z

Uncle Bob posted a message in which he points out some of Scrum’s shortcomings. It’s a well-put and thoughtful critique of the places where Scrum falls down or is silent.

Scrum carries an anti-management undercurrent that is counter-productive. Scrum over-emphasizes the role of the team as self-managing. Self-organizing and self-managing teams are a good thing. But there is a limit to how much a team can self-X. Teams still need to be managed by someone who is responsible to the business. Scrum does not describe this with enough balance.

Reading this list, you’ll probably realize two things.

Your team isn’t really doing Scrum
Your team has figured out practical ways to work around these shortcomings or skip them entirely.

In the end, this is a critique of strict Scrum, and really not of Agile itself. It kind of reinforces how nebulous the space still is.

Scrum / Agile’s inherit shortcomings? Uncle Bob Martin’s 7 theses via @markneedham

The "Choose Python" Manifesto

2010-02-05T14:34:24Z

Yes! A Python manifesto to add to my informal collection. It’s nice to have such passion around a language.

Here’s a funny part:

Choose to finish early and laugh at your colleagues as they waste their miserable lives bowing down in subservience to that sadistic little C++ compiler.

Busting on C++ never seems to go out of style.

Near as I can tell, this comes from Alan Issac, associate professor at American University. If you know better, please holler at me.

Chose Python (pdf)

via “Choose Python” [For Some Value of “Magic”]