State of the Art - Don't Comment Your Code

I was listening to a Java Posse podcast this morning, and the hosts were discussing the pros and cons of putting comments in your code.   I consider myself a software craftsman, and a big part of that involves writing readable code.  I have done it often enough to know that good code really doesn't need comments, and by that I mean any non-Javadoc comments.  (And only your API code should have those.)

The fact that the Java Posse guys seemed unaware of this as a practice surprised me, so I did a little digging with the expectation that this "obviously beneficial" practice was being used by most, but not all developers.  I was surprised to find a number of fools who were dismissive of the idea, in addition to a number of obviously intelligent people who agreed with me.  Apparently this is not yet a mainstream concept.

I have worked at a lot of places, and the best, most maintainable, easiest-to-change code I have ever seen was all written at my current workplace where "no comments!" is the norm.  Really top-notch programmers can certainly still create excellent software with large methods, confusing method and variable names, and other code smells.  Mere mortals will struggle to change such code, though.

So why, if this is so obviously beneficial, is it not standard practice across the board to avoid comments whenever possible?  I have a few ideas, based on my experience in different software shops:

• Some codebases are changed very slowly or simply have the expectation that any change will be time-consuming and expensive.  Such code is probably internal-only.  In this case it would be less obvious that the code is hard to change.
• Many programmers don't consider themselves professionals, and don't try to keep their skills up-to-date with constant self-education and practice.
• I'm wrong.

While the third bullet point has happened before, I don't think so in this case.  I suspect rather strongly that the second bullet is the most likely one.  It's easy to let your skills and knowledge go stale, so that's what most people do.

If that describes you, beware!  You're not likely to remain employed in this brave new world if you're not competitive.

Google does 20%, we do 10%

I work at Cengage Learning (my views are my own, they don't represent the company, etc, etc, etc), and we recently started giving developers the option to make use of  "The Cengage 10".  This means that we can use 10% of our work time for a project that we're passionate about.

The idea is to drive innovation and make it a better workplace.  So far, I think we're successful at both goals, but it may be a little bit early to tell on the second one.  Doing this hasn't impacted delivery dates for normal business-driven projects.

We did put a couple of restrictions around it:

• If your team room really needs you (broken build, release problems, etc.), don't leave to work on your side project.
• You should work on a project with at least one other person.
• A "project" doesn't have to provide direct business value - it can be learning a new technology.

This works pretty well because we hired people who enjoy their work and don't need much supervision.  Treating good developers like losers who won't do any work without constant monitoring is a great way to get the good ones to leave.  (Until you're left with losers who won't do any work without constant monitoring.)

And yes, the idea came from the way Google treats its developers.

Expert Searching With Google

I found this site on "Power Searching with Google".  It describes how to get the most out of a google search. For 90% of my searching, a quick & dirty search (which is what I usually do) should be fine.  But that other 10% probably represents half of the time I spend trying to find things.  My usual strategy is to keep banging away & try new search terms.  The course recommends doing exactly that, but here are a few tips that I think will save a LOT of time for more specific searches:

• When searching for images, use the "search tools" and choose a color.  Black & white, gray, white or black in particular are useful for finding diagrams.
• Google scholar is great for finding authoritative search results.  
• I think that it is similar to searching with site:edu, plus some other academic sources.  
• Note the legal search results - court opinions are much clearer that I would have believed (and a lot more wordy).
• Site: is useful if you want to restrict to a particular site or subset of sites. 
• Restricting to site:gov would only give you official US government sites.  (You can use go.uk, go.fr, etc. to search other country govt sites).
• Restricting site:edu will only give you US educational institutions.  Useful if you want a more collegiate take on the subject.
• Filetype: can be useful if you want just a .csv or .klm (Google Earth) or a particular format.
• filetype:pdf might be worthwhile if you want a document that covers the topic.
• Combining site:edu filetype:pdf would (I think) restrict your search to something like "Academic papers on this subject", as opposed to abstracts or simple web pages.
• This page has a pretty good summary of the search features, most of which are automatic.

You can get as much (or more) out of Google search simply by exploring the interface and trying everything that they have available.  They have put a lot of thought and effort into it.

The Roman Numeral Kata

I've been pulling together a kata based on converting Roman numerals.  The idea is that after having people refactor this one to something relatively clean, they can test drive a different design.

I haven't settled on a good design just yet, though.  The concepts I want to drive home are:

• Excellent naming
• Small Modules
• Low Complexity
• Single Responsibility

Does anyone have a favorite problem space, or a solution to the Roman numeral conversion problem that really drives these home?

Linking Google Drive Docs with Evernote

There is at least one service (CloudHQ) that will keep them in sync for a fee.  What if your requirements are very lightweight, though?

In my case, I just want to be able to link a Google doc to a note.  What I have been doing is:

1. Open the doc in Google drive.
2. Click the share button.
3. Copy the link.
4. Paste it in Evernote with Cmd-K, Cmd-V.

That's not a difficult workflow, but it isn't as light as it could be.  

As an alternative, try doing a one-time install of the Google Drive app (if you don't see a button to install it at the link, that probably means its already installed on your machine).  Then you can use Evernote's built-in "attach files" button or menu shortcut to put a Google Docs link right in your note.  Just navigate to the right place in your local Google Drive folder and and click 'open'.

A Good Code Editor Is Easy To Find

I've been playing around with Sublime Text, which is a code editor with a very active community.  I thought it was nice, but after years of using Eclipse, no big deal.  However, some people whom I respect (the guys at Bitovi have turned me and several of my Coworkers on to it) insisted that it was the best editor for programming that you can find.

To decide for yourself, I recommend the videos that Jeff Way at Nettuts put together to improve your workflow.  Watch the first one (it's only 2.5 minutes long) to get a feel for whether it's worth watching any of the rest.  If you watch just a couple more, I'll bet you'll be hooked, though.

What do I like about it?  I'll summarize in terms that are the most important to me:

• Multi-platform (Linux, Windows and OSX - all platforms I use regularly).
• You can open a folder and use it like a project.  None of the long tedious "import" BS that you have to do in Eclipse.
• Quick file and symbol searching.  (Seriously, I can type command-P, part of a file name, "@" and part of a symbol to drill to a particular method in a particular Java class.  That's all kinds of awesome!)

I never much liked vi (though I can use it in a half-assed way), and I'm not all that thrilled with using a heavyweight IDE like Eclipse (the flakiness outweighs the benefits of having a continuous build too).

Now I can finally be one of those guys who is comfortable with just a shell and a stand-alone editor to do all of their programming work.  That's a level of nerd-cool that I have heretofore reserved for people like Magnus.

Maybe I should grow a beard.

Specializing Generalist: How Much of Each?

I just had a conversation with one of my teammates.  He's not happy with being seen as "The Javascript Guy", and prefers to be seen as a good all-around software developer.

He does make a very good point.  How much of our time should be as "generalists" and how much specializing in particular languages, libraries and toolkits?  How much time should we spend learning new things, vs time spent using the skills we have already built?

It isn't an idle question.  At the extremes, if you're constantly learning new things, you're always a newbie and not adding a lot of velocity to your project.  If you stick with the skills you have and apply only those skills, you will eventually be left behind by the march of technology, and obsolete as a developer.

My opinion is that the balance lies somewhere around 80/20, or even 90/10.  The majority of your time should be spent putting the skills you already have to good use.  I also think that the 10-20% time is spent in bursts, so the reality is that I'll spend 99% of my time exercising skills I already have, and building just a but of new mental muscle.  Then I'll discover a need for new skills and spend 90% of my time learning *that* new thing, which slowly ramps down as I use it.

What do you think?  How "special" and how "general" should a good developer be?

What is software craftsmanship?

In a conversation with Patrick Welsh today, and his take on it was that a craftsman is someone who:

• Writes small methods.
• Uses excellent names.
• Keeps modules small.
• Test drives code.

The context of this is that it is possible to do all of these things in Javascript.  Claiming that JS is fundamentally different from Java (or any other modern language) is a poor excuse for not being a craftsman.

I tend to agree with him, and disagree with John Marx's statement that you can be a software craftsman without doing the above things.  I think that John's point was that technique != mindset.  My disagreement is that at the current time, using these techniques is the way to be a craftsman.  As techniques and tools evolve, the definition of craftsmanship will evolve.

What do you think?

Death by Oversight: How much overhead is too much for an agile project?

I had a great discussion with one of my coworkers today.  He felt that we were adding a lot of noise to our current project due to the number of "fluff" people on our project.  In his opinion, anyone who wasn't spending most of their time on a keyboard (software developer, analysts creating stories, QA) is overhead.

Such people (which list includes me, BTW) have the following negative effects:

• Communication overhead / Noise - people doing the actual work are often asked by multiple people how something works or why a particular choice was made.
• Meetings - we can be a source of meetings and other discussions apart from the "noise" above, if only to justify our time on the project.
• Duplication of effort - this has definitely happened to us.  More than one person steps up to get something done (analysis of a problem, breaking down & estimating a set of stories, etc.) and because we're not all communicating face-to-face, they don't work together on it.
• Climate of fear - feeling that you have to please a lot of people with different agendas can create a climate of fear, even if most or all of the people involved have good motives.

It was a compelling case, and I don't have any easy answers.  Some worth considering:

• Make sure all of the "fluff" people are aware of the problems above!  Stating the problem clearly is the most important step in solving it.
• Reduce the fluff by having some people step out of the project, or by changing their role to something other than a decision-maker.  (For instance, my role could be developer + management bitch for buying hardware & approving access to resources, and I can step out of most of the planning & oversight work.  Hmm... that actually sounds like a lot more fun than what I've been doing.)

It's More Fun With Two: Pair programming done right

A couple of months ago, I blogged about some of the mechanics of pair programming.  This post is more about the attitudes around it and supporting practices.

Pair programming is often held up as the one true path to good code, but there are some dissenters.  Many of these people aren't naysayers, but instead believe that while pair programming has it's place, so does writing code in blessed solitude.  Some (at least anecdotally) think that pairing is the root of all evil.

The truth isn't somewhere in between.  Pair programming really is coding nirvana, but only if you do it right.

Keys to Success

I have spent the last three years in a software development organization that has strong values around pair programming (after spending 20 years in 23 other organizations that didn't).  It is pretty consistent - most of the seven teams practice nearly 100% pair programming.  Most are pretty good at it.  Some are awesome at it.  In my experience, the following keys are what allowed them to reach levels of never-before-seen awesomeness:

• People - you have to eliminate assholes from the organization.  If you have developers who belittle or bully other developers, they will destroy your ability to make this work.
• Frequency - you have to do it a lot.  By "do it", I mean pairing pretty much all of the time, and swapping pairs daily or almost daily. (Some people advocate swapping even more often, but I don't have direct experience with that practice - yet.) Do this for at least 2 months before allowing any solo work.  You simply can't get good at it unless you have a lot of practice.
• Urgency - build and maintain a sense of urgency across the team.  All of the developers should be motivated to get stories all-the-way to done as soon as they can, with zero defects.
• Communication - pairs should be constantly discussing, whiteboarding, and calling over a product owner (or proxy) to clarify details.

Benefits

I'll assume for the moment that your organization doesn't practice pair programming, or does so only on a part-time basis.  Why should you go to the trouble?  What will you get out of it?

First of all, there are some sound psychological reasons.  From a programmer's perspective, it is just plain more fun to work with a pair all day.  You keep each other honest, which means that you never go home at the end of the day feeling like you haven't accomplished much. Productivity really is its own reward.  It's hard to overstate the profound impact of going home at the end of the day - almost every day, with a sense of accomplishment.

It also feeds our social needs.  You spend the day in a relaxed conversation (and occasional heated debate), talking about something you both enjoy and understand.  How often do you spend 6 or more hours talking to your significant other about something you're both into?  Once the team has been together a while, you'll also get a sense of camaraderie, as well as building up a lot of inside jokes.  I haven't worked at many jobs where I felt as close to my coworkers as I have on projects were we constantly pair.  (This is also a good reason to look for a sense of humor when you interview people.)

Finally, there are a number of excellent business reasons.  Here is a logic-chain for you to consider:

• When developers are committed to pairing and feel the need to work fast, they work harder to understand each other.
• To help understand each other, developers usually draw pictures on a whiteboard or paper.
• When people communicate visually as well as verbally, they understand what the other person intends to do much better.
• When people understand each other's intentions and plans really well, they can point out flaws, solutions to the flaws, and additional opportunities for improvement much more quickly and effectively.
• When developers are communicating quickly and effectively, you get the benefit of two programmers' experience in a fraction of the time, with almost no software defects.

This means high-quality code done quickly.  There aren't too many customers who would say no to that.

Pitfalls and objections

Of course, no plan ever survives contact with the real world.  There are a lot of things that you have to adapt to.  Here are a few of the problems I have seen and their solutions.

Problem:

How do you get a team to feel a sense of urgency, communicate a lot and pair all of the time?

Solution:

Tell them what you want them to do and why.  Coach them to do it.  It's simple, though not easy.  Hire an agile coach or two if you can't do it yourself.  And remove any jerks from the team.  (Like I said, simple, but not easy.)

Problem:

Noise!  Isn't it really distracting to work in an environment with constant chatter and movement?

Solution:

This one mostly solves itself.  You'll be amazed at what people can adapt to.  If the acoustics in your space really suck, look into some sound absorbing ceiling tiles and baffles.  They can make a pretty big difference.

Problem:

The developers on my team just aren't committed to this.  They're not jerks about it, they just don't believe in it.

Solution:

This is one of the most difficult problems, and probably the most common.  The only answer that I have seen work is to have the committed people significantly outnumber the non-comitted people.  Culture tends to follow the majority.  If you have to, start with a small seed team and outnumber them with some contractors with the right outlook and skills, then slowly (every month or so) add another person to the team.  When it gets large enough, fission the team into two teams and repeat.  This is expensive, but worth it.

Problem:

There really are some things that are best done solo.  How can I tell my team that they have to pair on them when common sense dictates that it's more efficient to split them up?

Solution:

There are probably far fewer thinks that are better done un-paired than you think.  Enforced pairing at the outset helps the team identify more clearly what they are.  Just tell them that - they'll probably get it!  Give them a time-frame if you must, but it should be no less than 2 months.  After that, he more obvious things like fixing simple UI bugs can be done solo… though if you're doing it right, you may find that you don't have any UI bugs, simple or otherwise.  I'm just sayin'...

Problem:

I can't sell this to my business.  They'll never let us do it!

Solution:

How hard have you tried?  Can you enlist some help in selling the idea to them?  Just as important - do you really need their permission, or will your boss (or his/her boss) provide enough air cover to let you get it done?  If not, maybe your business is filled with jerks and you should just find another job.  I have worked in automotive companies before and I feel your pain.

Summing it up

Pair programming really isn't just the best way to get a project done quickly, it's also the most fun.  Most programming shops don't practice pairing because they haven't tried doing it without understanding the keys to success or the challenges they were likely to encounter, then came to the conclusion that "pair programming doesn't work".

Doing it right really is simple: stress communication and urgency, and insist that your developers pair 100% of the time until they get good at it.  It's a winning formula.

Discussion Question

What other problems could derail implementing pair programming in your shop?