Ship It! by Jared Richardson and William Gwaltney Jr. - Book Excerpts

tldr; warning

Tools and Infrastructure

Manage Assets

How Do I Get Started?

If you’re not using any type of source code control for your project, make it your top priority.
According to a recent survey, some 40 percent of IT shops in the United States do not use any source code or version control product at all, so we know you’re out there.

1. Evaluate a few SCM systems. We heartily recommend CVS or Subversion. Both are free and used by some of the largest software companies in the world. If you choose a commercial solution, these products will still give you a baseline to compare their feature sets against.
2. Learn how to use your SCM.
3. Generate a single-page quick-start guide that shows how to use the system for common operations.4. Show the system to your team. Be sure everyone is comfortable with the system.
4. Import your code and supporting files.
5. Start keeping all your files in the SCM.

Am I Doing This Right?

First, are you actively using the system? If you go weeks—even days—between code check-ins, you aren’t using the system actively. This defeats the whole purpose (backing up your work and maintaining an accurate fine-grained history). Even if your code isn’t ready for the production tree, it can be placed in a private or personal area of the system.
If the hard drive on your workstation crashed right now, how much work would you lose? If it’s more than a day or two, consider changing the way you work.
Also, how long would it take you to get a new machine up and running for development? Are all of your build scripts and development resources checked in?
Can you perform SCM operations quickly? If it takes you twenty minutes to check out code and another fifteen minutes to put changes back in, you won’t do check-ins frequently. Your basic interactions must be fast.
Operations such as fetching differences can put a heavy load on the CPU and disk drives. Quite often companies will put their SCM software on an antiquated computer, making all interactions painful.
Hardware is cheap, but developer time is expensive. Whatever it takes (training, hardware, or new SCM software), be sure that your SCM is fast enough to keep up with you.
Are you backing up the SCM’s repository? If the building burns down tonight, do you have an off-site backup that you can use to restore to another machine? A great SCM does you no good if the data it’s storing gets lost. Be sure you are getting a complete, weekly off-site backup at a minimum.
Finally, do you know your system well enough to perform these basic operations easily? Here’s a minimal list of operations that you need to know:

• Check out the entire project.
• Look at the differences between your edits and the latest code in the SCM.
• View the history for a specific file—who changed this file and when did they do it?
• Update your local copy with other developers’ changes.
• Push (or commit) your changes to the SCM.
• Remove (or back out) the last changes you pushed into the SCM.
• Retrieve a copy of the code tree as it existed last Tuesday.

Warning Signs

• No activity in the repository. An unused repository is a useless repository. You should see activity every hour through the day as individual developers check in and check out regularly.
• Incomplete repository. If the repository contains only some of the files needed to build your product, it’s not pulling its weight. Beware of “experimental” release or test trees that aren’t being stored in the repository or of contents of critical XML files or databases.
• Slow access. If it takes a long time to check in or check out files, people will eventually stop using it—even if they are using it now.
• Lost files, corrupted files. Some version control systems (made by certain large, unnamed companies) are known to “eat” files on a regular basis. Upgrade to a real system, such as the freely available CVS or Subversion.

Script your Build

How Do I Get Started?

If you just inherited a new product without an automated build, you should take these steps immediately to get a build script in place:

1. Have a team member manually build the system while you take notes.
2. Define the individual build steps.
3. Pick a build tool but be prepared to revisit other options if this tool becomes too burdensome.
4. Incrementally script each step; eliminate manual operations one by one.
5. Run the script on another workstation. This step will catch any accidental workstation-specific code.
6. Now have another team member try to use the script without your help.

When you complete these steps, you will have a script that should work for everyone.

Am I Doing This Right?

If you’re using your manual build system properly, you will be able to build your entire product:

• With one command
• From your Source Code Management system (SCM)
• On any team member’s workstation
• With no external environmental requirements (such as specific network drives). If you have issues with any of these items, have another look at your build process.

Warning Signs

• Your build contains any manual steps.
• Your build script has to be modified to run on different machines.
• Only a few team members know how to edit the build script.

Build Automatically

How Do I Get Started?

You must already have a good build system in place to move to the next level with an automated build system.

1. Select an automatic build system to use. Do not write your own.
2. Obtain a “clean” machine to run on.
3. Install your automatic build system, and configure it for your environment. Document every step of the install.
4. That’s it! You can set up this type of system fairly easily, and the return on investment (known to management as ROI) usually reaches the break-even point in the first few months. If management doesn’t see the benefit, run the system on your own machine at first. People who have never used a CI system often need a live demonstration to appreciate how powerful the concept is.

Am I Using This Right?

If you’re using an automatic build system (or a CI system), you are far ahead of most software teams. But there are still a few questions you need to ask yourself:

• Do you have tests in the system? After all, no one cares if it compiles if it doesn’t run.
• Is anyone paying attention to the system? Are the notifications turned on?
• Does your build get fixed quickly or stay broken for days?
• Does your build finish in a reasonable time, or does it take too long to complete?

If you can answer these questions favorably, your team will be able to spend their days adding features instead of tracking down which line of code broke feature X sometime during the last six months!

Warning Signs

• Your automatic build system breaks frequently.
• Your team ignores broken builds.
• The build stops running, and no one notices.

Track Issues

How Do I Get Started?

If you don’t currently have an issue tracking system, don’t wait. Don’t delay your transition until you can transfer every issue ever encountered.
That’s an admirable goal, but don’t wait until you have your manual system clean before using the automated system. Just start using it as soon as you can. Enter the new issues in your new system, and over time it will achieve the critical mass of information that makes it a vital resource. If you have the time to populate the new system, great! But don’t make it a requirement for use.

1. Pick an issue tracking system (Appendix D, on page 172).
2. Set up a test system for yourself, and learn how to use it.
3. Generate a one-page quick-start guide for your internal users.
4. Start keeping all new issues in this system.
5. Move pre-existing issues over to the new system as time permits.

Am I Doing This Right?

If you track issues with any sort of a system, you’re doing great. The real question is whether you store enough information in the system and whether anyone uses the system internally. Use these questions to gauge your success:

• Can you generate a list of the top-priority, unaddressed issues? How about the second-tier issues?
• Can you generate a list of last week’s fixes?
• Can your system reference the code that fixed the issue?
• Do your tech leads use this system to generate to-do lists for development teams?
• Does your technical support team know how to get information out of the system?
• Can you system notify “interested parties” so tech support (and others) can see when an issue is fixed

Warning Signs

• The system isn’t being used.
• Too many small issues are in the system.
• Issue-related metrics are used to evaluate team member performance.

Track Features

How Do I Get Started?

Getting started here is pretty much the same as How Do I Get Started? in the Issue Tracking section.

Am I Doing This Right?

You’re in good shape if the following is true:

• You use this system as a first stop when it’s time to generate the next release’s feature list.
• You routinely record new product ideas in the system.
• Many of the submitted features are rejected. Otherwise, you’re culling them before you enter them.
• You can generate the last product version’s “new feature” list by running a report from this system.
• Your stakeholders can easily check on feature status, and they get warm fuzzies because it matches their expectations.

Warning Signs

• No new features are being added.
• Everything is priority one.
• Features get added but never implemented.
• Irrelevant features are being added.

Use a Test Harness

How Do I Get Started?

If your team has no tests at all, you may want to discuss it with your tech lead (or manager). You can add tests to your areas of responsibility to show the benefit, but for maximum benefit the entire team should participate as well.
If your team is already writing tests, find out what they’re using for a framework. Many developers write their own framework—don’t go there! But if anyone in your shop has settled on a standard framework or tool, find out what it is and why they selected it; leverage their experience and expertise.
Once you’ve selected a framework, use the defect-driven strategy to create tests for your code. We strongly suggest you create mock client tests, and that you run all your tests in a CI system. A CI system is the best way to assure the tests are run regularly.

1. Select a testing tool or toolkit.
2. Start adding tests to problem areas.
3. Ensure that your tests are being run in an automatic build system.

Am I Doing This Right?

Your answers to these questions will make it clear if you’re on the right path:

• Is your test suite effective? Are your tests catching bugs?
• What are your code coverage14 numbers? Are they increasing over time?
• Is the product you’re testing stable?
• Are the tests being run automatically?
• Do your tests tell you whether they pass or fail? (If you have to manually determine whether they passed or failed, they aren’t automated.)
• Does everyone in your shop have the ability to add tests? (If not, the framework is probably too complicated.)

Warning Signs

Have another look at your strategy if your tests:

• Aren’t being run
• Never catch any problems
• Take too long to run
• Require significant effort to maintain

Pragmatic Project Techniques

Use The List

Maintain a prioritized list of things to be done with the estimated time required to address it and its status.

How to Get Started

1. For an entire day, write down every task as you work on it (this will be your “finished” list).
2. Organize whatever daily task list you do have into a formal copy of The List.
3. Ask your tech lead to help you prioritize your work and add rough time estimates.
4. Start working on the highest-priority item on The List—no cheating! If some crisis forces a lower-priority item higher, record it.
5. Add all new work to The List.
6. Move items to your finished list as you complete tasks (this makes surviving status reports and “witch-hunts” much easier). The act of creating The List forces you to organize and prioritize your work. Just as keeping a diary helps you think through and understand what you’ve been doing, The List helps you sort out your current workload but in a fairly high-level, lightweight way.
7. Review The List every morning. Update it whenever new work pops up. . . especially the last-minute crisis tasks; you’re likely to forget about those when someone asks you what you on earth you did all last week.

You’re Doing It Right If...

• Is every one of your current tasks on The List?
• Does The List accurately portray your current task list?
• Did the tech lead or customer help you to prioritize The List?
• Is The List publicly available (electronically or otherwise)?
• Do you use The List to decide what to work on next?
• Can you update (and publish) The List quickly?

Warning Signs

• You fail to add tasks to The List because you’re “too busy.”
• More time is spent updating The List than completing the tasks.
• It takes weeks for team members to complete individual items on their personal lists (hint: the items are too big).
• The List is updated less than once a week.
• Priorities on The List don’t match “real” priorities.
• The List is a closely held secret, not visible to anyone outside your team.
• In addition to the team’s list, there are other publicly available versions that differ.

Tech Lead

Have a Tech Lead in the Project. The tech lead has several major areas of responsibility that will vary by company and team composition. The following is a minimal list of a tech lead’s responsibilities:

• Set direction for team members.
• Orchestrate your project’s feature list.
• Prioritize your project’s features.
• Insulate your team from external distractions.

How to Get Started

If you aspire to be a tech lead, you need to prove you’re ready to handle the additional responsibility. Look over the job requirements, and strive to live up to them. Voluntarily perform as many of the tech lead duties as you can. Don’t wait for the job to fall into your lap; demonstrate that you are trying to earn the position and can handle it well.
Use The List for your personal work but also keep one for your team. Monitor work in progress while keeping an eye on upcoming projects.
Evaluate your team’s process. Locating the weak spots and finding practices or concepts to address problems will give you a new perspective. For example, if your team is having trouble keeping the code compiling, then you should set up a CI system on your desktop to help solve the problem.
Don’t give up if you aren’t promoted to tech lead right away. Continue learning and growing for the next assignment. Not everyone has the temperament for a tech lead role, but working toward it gives you a broader picture of the entire project, which makes you a more productive team member. You become a better developer by thinking about and considering how you’d be a tech lead.
If you’ve just become a tech lead, create a rough road map. Chart where the team currently stands and the direction you want them to go. What problems will you address? What work will you encourage?
Make a list of all known problems. Then survey the team to see if they know about additional problems. When you think you’ve arrived at a real list, decide which items you can address and which you can’t.
Daily meetings are a great way to keep track of your team’s work without smothering them.

You’re Doing It Right If...

As your team’s tech lead, you should be able to answer these questions favorably:

• Do you know what every member of your team is working on?
• Can you generate a project status summary in less than five minutes?
• What are the next five to ten features for your product?
• Can you readily list the highest-priority defects for your product?
• What was the most recent problem you cleared up for a team member?
• Would a team member come to you if they needed an important issue resolved?

Warning Signs

Here are some warning signs that your tech lead is ineffective or overbearing:

• Lacks big-picture view of every team member’s work direction
• Causes work to halt when they show up
• Takes credit for the team’s work
• Fails to solve problems, or worse, causes problems
• Inaccurately forecasts work time lines
• Is unaware of team members’ technical proficiencies and/or what team members want to learn
• Is oblivious to personality clashes on the team

Coordinate and Communicate Everyday

How to Get Started

If you’ve never had daily meetings before, you’re in for a real treat! Here are a few ideas to get them rolling:

• Be sure everyone knows the format (which questions you want answered).
• Everyone must answer the questions. There are no passes, and no exceptions.
• At first, be lenient on the time restriction. A lot of new information is exchanged in the beginning, so you must allow communication to flow freely.
• Hold your meetings at the same time and in the same place, every day. Make daily meetings a habit, not a chore to keep track of.
• Post topics that are discussed during daily meetings on a web page or plog
• Pick a person to start the meeting, and then move clockwise (or counterclockwise) through the group. Randomly picking one team member after another is more apt to make them feel ambushed.

Stay Focused
Daily meetings can be a valuable tool if everyone stays on-topic. It’s important to be very specific in the meeting, Don’t say you’re “70 percent done.” Instead, say that today you added the login screen, and though it’s not functional yet, it should be tomorrow. Pause for a moment if someone says, for instance, that the login screen is broken, and ask them to describe the problem in more detail (e.g., “It doesn’t communicate with the authentication manager yet”). When a project is new, the tech lead runs this meeting, but eventually the leadership responsibility should rotate throughout the group. Use these daily meetings to grow your leaders in-house.
If a topic starts to take on a life of its own, or the meeting starts turning into a problem-solving session, the leader should quickly take it “offline” by having the involved team members get together privately after the main meeting. There’s no reason the entire team should have to listen to Jim and Sue brainstorm for half an hour on a problem that only they have. They can give everyone a short overview of the solution after they’ve found it.
Several prominent development methodologies insist you limit meeting times by having everyone stand. That works, but if the meeting participants are disciplined about being brief (or if the leader is disciplined about keeping everyone on-topic) standing shouldn’t be necessary. Try it both ways to see what works for your team.

You’re Doing It Right If...

If you are already having daily meetings, that’s great! Here are a few guidelines to be sure you stay on-track:

• Are the meetings useful? If no one in the group is learning anything, the reports might be too terse. If more details are needed in a particular area, push those topics into a side meeting with a smaller group. However, the two-minute rule is a guideline, not a law. You may find thirty seconds is just fine, or you may need three minutes.
• Are meetings consistently held the same time and place every day, or do they fluctuate? Having daily meetings at the same time and place makes it easy to remember. Meetings can move occasionally, but avoid mixing things up frequently.
• If you stopped holding the meetings, would people complain? They should! The team should come to depend on the daily meeting to stay “in the loop.” If the meetings can be dismissed, then they weren’t providing value. The team should rely on the daily meeting as an invaluable resource.

Warning Signs

Daily meetings are a great tool. But like any tool, they can also be harmful if handled improperly. The following are a few warning signs that your daily meetings have drifted off-course:

• Each team member takes ten minutes or more.
• One team member consistently takes up as much time as the rest of the team put together.
• People are heckled in a mean-spirited manner. Joking among team members is good (and to be encouraged), but if your daily meetings turn into sniping sessions, they’re not productive anymore.
• Deal with the snipers.
• Your meetings consistently start (or finish) late.
• The meetings become content-free, with developers making claims such as “I’m still 90 percent done” or just “workin’ on the Frozbot.”
• Team members ramble or forget to report things they’ve done. Privately ask these team members to write down what they’ve done, so they stay focused during meetings and keep their report concise. They would also do well to have their own copy of The List to help keep them organized.

Review All Code

How to Get Started

Code reviews are great tools! Once you get in the habit, you’ll wonder how you ever wrote decent code without them. Use these tips to get started:

• Be sure everyone understands the type of code review you have planned. Review frequently on smaller blocks of code. Don’t wait for weeks, accumulating hundreds or thousands of lines of changes. No MAD reviews for your team!
• Have one of your senior team members sit in on each code review for the first few weeks or months. This is a great way to share knowledge and get the reviews on a solid foundation.
• Make sure your code reviews are lightweight. It’s better to review too little code than too much. Having two overlapping reviews is better than having one larger one.
• Introduce a code change notification system (see Practice 14, Send Code Change Notifications,, on the following page) at this time. It’s a great complement to your code reviews, and it helps to remind team members who forget to ask for reviews.
• Make sure you have management buy-in before requiring all team members to participate.

You’re Doing It Right If...

• Do code reviews get an automatic approval? This shouldn’t happen unless everyone on the team is perfect.
• Does every code review have major rewrites?If so, it indicates a problem somewhere: either with the coder, with the reviewer, or with the tech lead (who gave the directions that the coder and reviewer are using).
• Do code reviews happen frequently? If the time between reviews is measured in weeks, you’re waiting too long.
• Are you rotating reviewers?
• Are you learning from the code reviews? If not, start asking more questions during your code reviews.

Warning Signs

• Code reviews are infrequent.
• The majority of code reviews are painful.
• People avoid checking in their code because they don’t want a code review.
• Team members who have reviewed code can’t explain what it does or why it was written.
• Junior team members review only other junior member’s code.
• Similarly, senior team members review only other senior member’s code.
• A single team member is everyone’s preferred reviewer.

Send Code Notifications

How to Get Started

There are several ways you can introduce code change notifications.
We’ve used both manual and automatic systems. With a manual system, you type emails by hand (pasting in code diffs by hand) and send them to team members. With an automatic system, a program that watches your SCM generates notices and sends emails.
Both are valid approaches, but automatic is always preferable. However, getting an automatic system in place may be difficult in your environment; if that’s the case, use the manual method. Make sure your team knows about the notifications before they start arriving.

You’re Doing It Right If...

Notifications must be regular and trustworthy.
Don’t send out five-meg diffs!

Warning Signs

The only real problem you need to watch for here is dependability. The notifications must be reliable. If your team members don’t believe the mail will be sent after code changes, they won’t come to depend on notifications. This is easier to fix with an automatic system than with a manual one, but in either case, you must take this problem into account.

Tracer Bullet Development

How to Get Started

The best way to get started with TBD is to pick a project and try it out.
Review the concept with your teammates before you get started. We’d suggest you try a smaller project first to get a feel for how TBD works.

• Define your system objects.
• Define the interfaces between them.
• Write the interface stubs.
• Make the stubs talk with each other.
• Fill in the stubs with functional code.

You’re Doing It Right If...

• The entire system is always up and “running.”
• Team members understand the system objects as well as “their” objects.
• Team members feel comfortable helping out with other system objects.
• You can rewrite large portions of your code base and nothing breaks.

Warning Signs

• Team members argue for hours over the “right way” to design an interface.
• The end-to-end system never actually runs end to end.
• Builds are frequently broken because interfaces were changed and the consumers didn’t know.
• You have only one big honking system object.
• You have 700 itty-bitty system objects.
• The team has been working for months and the system still doesn’t have compiling stubs.
• The team has had compiling stubs for months and no working features are in place.