A SCOUT IS A FRIEND TO ALL, AND A BROTHER TO EVERY OTHER SCOUT, NO MATTER TO WHAT SOCIAL CLASS THE OTHER BELONGS. If a scout meets another scout, even though a stranger to him, he must speak to him, and help him in any way that he can, either to carry out the duty he is then doing, or by giving him food, or, as far as possible, anything that he may be in want of. A scout must never be a SNOB. A snob is one who looks down upon another because he is poorer, or who is poor and resents another because he is rich. A scout accepts the other man as he finds him, and makes the best of him — “Kim,” the boy scout, was called by the Indians “Little friend of all the world,” and that is the name which every scout should earn for himself.

I subscribe to the tenets of Java, to the gospel of write-once-run-everywhere (even though, like so many other gospels, this one has never been successfully implemented in the real world). I believe in the strong typing of objects,the early binding of classes, and the clear separation of application tiers, world without end, amen.

I also attend the church of open source software, with its mutable prayer books and receptivity to revelation in the latter days. I believe in web standards, in XML validation, and in the W3C. These are my fervently-held creed, the values that guide my every line of code, and I scoff at the infidels who would disagree.

Except, of course, when I have to work with those infidels, and when those infidels have really great ideas or services I’d like to leverage. In both enterprise and web development, there’s no true church to which everyone subscribes, no matter how hard architecture steering committees try to make it so. Like it or not, your Java code has to co-exist with COBOL and Perl, your PHP needs to be VBScript-aware, and if your .NET can work with LotusScript, so much the better. We live in a diverse technology ecosystem, and we had best be able to extend a hand or accept assistance from programming worlds that are bizarrely alien to our preferred approach.

Write code that can be leveraged across the enterprise, learn the lingua franca of your environment’s technology, and strive to “play nice” in the bigger sandbox.

Once upon a time, I wrote a web portal using Lotus Domino. It was pretty well self-contained, using Domino data sources and APIs with just a smattering of JavaScript. Because everything it did happened on Domino servers, it was fast and self-contained, easy for a Domino expert to maintain in the standard Lotus tool set. And, like so many things that belong to a single programming ecosystem, it was not especially scalable or flexible.

Opening up the portal to other environments was an arduous refactoring effort, but it paid off. With a clear separation of tiers–business logic in web services accessed via SOAP over HTTP, the presentation layer in modular portlets that relied on CSS and JavaScript, and agnostic container-managed data sources–I was able to swap out pieces and make adjustments to the application without breaking a lot of interconnected pieces. There was still some Domino in the mix for a long time–a web service that delivered e-mail information–but it was far less dependent on Domino, so when the decision to switch mail platforms came along the code-level work was minimal to maintain the functionality. Even better, the services that ran the portal could be accessed by other applications, offering reusability, one of programming’s holy grails.

When developing services that are going to be leveraged across platforms, in places you may not even imagine possible in the initial design, simplicity is the key to flexibility:

• Receive and return primitives: sending objects over the wire in SOAP is both expensive and limiting. You can have a strong object model on the service side and on the client side, but in the communication layer, break things into integers and strings. Converting a .NET object into a Java object is tricky at best; complex types being passed between Java and ColdFusion or PHP is a recipe for disaster.
• Use lightweight service transports: my original Domino portal used a lot of DIIOP, an IBM flavor of CORBA; it caused me grief to no end because it was so resource-intensive, more than a little buggy, and difficult to use outside the IBM environment. XML-RPC was a good, if clunky, middle step, allowing a LotusScript service to work easily with a Java client. SOAP (originally Axis, later XFire) was better; REST, with its reliance on the standard HTTP protocol model, would have been better yet. If you can expose your API as a set of URLs, you’ll find many more friends than if you require a lot of proprietary components.
• Use XML (with a DTD) for sharable data: most modern programming languages can use XML easily; and even languages like COBOL and LotusScript can work with XML by brute-force text parsing. It’s the closest thing we have to Esperanto in the programming world, and a great tool for cross-platform communication. Even if you don’t think the data will be shared across platforms, using XML up front will save you a lot of work when the inevitable request for integration comes along.
• There’s nothing wrong with text files: for simple document management and configuration settings, plain text (or properties/.ini files) are a great cross-platform solution. ASCII is supported on most platforms, and on those where it isn’t (I had to work with EBCDIC a few times on the z/OS platform with Domino), it’s usually possible to convert without too much pain. Even better than its accessibility to programming platforms is text’s accessibility to human eyes: a lot of troubleshooting can be done in vi or Notepad if an application’s data and configuration is in plain text.

I’m still a believer in the Java model, of course, and I like to see Java code used to do great things. But I’ve learned that a dose of ecumenicism is a useful tool for keeping the peace and making friends across the spectrum of technology confessions.

Every Scout in the United States learns the legend of the “Unknown Scout.” In 1909, an American businessman, William Boyce, was lost in the fog in London (this was before the Clean Airs Act restricted the burning of coal, and London’s fogs were really more a noxious smog than a quaint low-lying cloud). A boy emerged from the fog and helped Boyce get back to his hotel. When Boyce offered a tip, the boy refused, explaining that he was a Scout and simply doing his daily Good Turn before disappearing back into the fog. Boyce was so impressed with the Scout ethic that he brought Baden-Powell’s “Scouting for Boys” back to the United States, thus launching the Scout movement in North America.

Like most good legends, this one has some holes in it. Apparently there wasn’t really a fog that day, and the boy just helped Boyce get across a busy street. A nascent Scouting culture already existed in the United States and Canada, founded by Dan Beard and Ernest Seaton, and in fact the Woodcraft Indians and Sons of Daniel Boone greatly inspired Baden-Powell; B-P’s version of Scouting would probably have made its way over the Atlantic without that helpful Scout. But like most good legends, it’s a useful one, and illustrative of the Scout spirit.

A SCOUT’S DUTY IS TO BE USEFUL AND TO HELP OTHERS. And he is to do his duty before anything else, even though he gives up his own pleasure, or comfort, or safety to do it. When in difficulty to know which of two things to do, he must ask himself, “Which is my duty?” that is, “Which is best for other people?”—and do that one. He must Be Prepared at any time to save life, or to help injured persons. And he must do a good turn to somebody every day.

Scouting for Boys, Robert Baden-Powell, 1908

Helpfulness involves offering up something that we have to someone who lacks it. In information technology, the thing that we have an abundance of is, of course, information. We have access to tons of data, and our daily bread is extracting, manipulating, and distributing that information in useful ways.

Simply providing information, though, isn’t helpful. Helpful information is specific, timely, and relevant. The Scout who helped Boyce (in the fog version of the legend) could have given a lot of information to the befuddled businessman. He could have told him that they were standing in the city of London, and that the fog was especially thick that day; a certain kind of Scout could also have told him the temperature and dew point, explained the effect of prevailing winds on the fog, and suggested that the composition of the fog was largely coal smoke and a North Sea low pressure system. All good, true information, but all horribly useless: the Scout would not have been helpful at all by giving those facts. Boyce needed task-specific information–how do I get to my hotel?–and that’s what the Scout provided.

As programmers, we need to be in the habit of providing the same kind of targeted information: to our managers, our business partners, and each other. A good place to start practicing that habit is in the code we generate:

Comment only what requires a comment, and strive for readability in your code.

We’ve all seen, and been guilty of, unhelpful comments in our code. An unhelpful comment isn’t necessarily a false comment; it’s just one that doesn’t aid in understanding the task the code is trying to accomplish. For example, a lengthy comment on the inner workings of SOAP and the implementation of a Jakarta HTTP client to negotiate an XML-RPC connection might be fascinating, but it has no place in the code itself. Tell me what you’re getting from that SOAP source, not how you’re getting it; if your code is clean, I can figure out how it works.

Commenting the obvious but skipping the difficult is another sign of unhelpful code. When I see source code where simple iterator loops and string parsing functions are heavily commented, but an obscure and obtuse method has no comments at all, I’m nervous; I suspect that the person who wrote (or copied and pasted) the code doesn’t really know how it works, either, and I start to wonder if those other comments hold water, either.

You can cut down your need for comments by writing readable code to begin with. One of the first places to start is with variable names. It’s all well and good to use throwaway names for purely instrumental variables–iterating over an integer called “i”, doing transient string manipulations on “s”. But if it’s going to persist for more than the scope of one method, or if it represents a business object, or especially if it’s going to be exposed in an API function someone else will use, then give it a real name. “Foo,” incidentally, is not a real name; nor is “bar” nor (as one of my Lotus Notes colleagues tended to name things) “chucky.” Since most modern IDEs offer type-ahead, and most modern languages don’t have onerous limits on variable name length, you can be verbose without wearing out your fingers.

I’m a fan of the much-maligned Hungarian notation system, at least in untyped, late-binding languages. It may be overkill in an IDE that lets you inspect an object’s type by hovering the mouse over it, or with tools that aggressively do type checking as you go, but in other cases–I’m thinking in particular of JavaScript, PHP, and LotusScript–encoding the object’s type into its variable name can save you grief down the road. Though one of the benefits of loosely-typed languages is that you can let things be a little slippery, it’s also one of the downfalls when developing in such a language across a team or over time; “strName” is a helpful hint, to your co-workers or to yourself in a week or two, what to expect of an object, so you don’t expect it to behave in a way that it can’t.

As one who has both developed and maintained a lot of code, I’ve learned to see myself like the Tralfamadorians in Slaughterhouse-Five: a four-dimensional being stretching off into the future. When I make my code clear and well-commented, I’m not only helping my teammates now, I’m helping the future me who will forget the nuances of the code almost as fast as it was compiled.

A SCOUT IS LOYAL to the King, and to his officers, and to his country, and to his employers. He must stick to them through thick and thin against anyone who is their enemy, or who even talks badly of them.

Robert Baden-Powell, Scouting for Boys, 1908

Loyalty is another of the Scout values that is in short supply these days. Employees and managers look on each other with mutual suspicion, if not downright paranoia, and we are all quick to cut the human nexus for short-term gain. A narrow instrumentalism defines our work relations, and threatens to bleed over into our personal lives as well.

While blind loyalty is certainly as much to be avoided as extreme self-interest, the Scout recognizes that a lack of loyalty is a huge risk. Loyalty is a corollary of trustworthiness; it is trustworthiness over time: someone who can be trusted tomorrow as well as today is someone who exhibits the brand of loyalty Baden-Powell expounded in 1908.

Programming by the Scout Law is unlikely to cause big changes in our work culture, but it can at least get us into the habit of thinking about how loyalty can be a value in information technology. We may not be able to inspire loyalty in our managers or our co-workers, but we can encourage loyalty in our code.

Loyal code is both backwards-compatible and future-proof; it recognizes that other code depends on it, and keeps the contract intact.

In enterprise development, dependencies build up quickly. A sign of a successful component is that it is reused widely, often in ways not known nor ever imagined by the original developer. This can be a benefit–if you already have a good wheel, you don’t have to spend a lot of time making something else round–but it can also introduce a significant risk, especially if the reused component is changed capriciously.

There are practices in programming that strive to reduce this risk. One approach is Contract Programming, where the relationships between code components are defined formally and the “contract” is strictly enforced at run-time. This is especially useful in a distributed, service-oriented environment, where code components are developed by different teams, and even different companies. It also requires significant discipline to define the preconditions, post-conditions, and class invariants at design-time.

Perhaps requiring a little less rigor, but still a good way to ensure that changes in code don’t break the relationships between modules, is test-driven development. In this methodology, tests are written before the code, and the tests are executed often in the development iterations. If tests are written explicitly to ensure that the integration points are functioning, problems in the implicit contract can be uncovered before they become serious.

Of course, it’s still possible for us to be careless about our obligations even if we’re defining contracts or running frequent tests. This is where a loyalty-oriented approach to writing shared components comes into play. A loyal mindset encourages these practices:

• Make as few methods public as possible; the fewer functions you expose, the fewer chances you have to break the contract.
• Keep your parameters and return values simple; passing a very simple bean with primitive or core getters and setters will simplify your interface and make it easier to extend, than if you have multiple parameters that can change over time and break dependencies.
• Do good design up front; understand how your methods are likely to be used, and then imagine how they might be used in the future: will your code scale if someone comes up with a novel use for your modules?
• Use deprecation when you’re planning to retire a function, rather than simply yank the rug out from under a client; provide fair warning that a method signature is going to change, and continue to support older interfaces for as long as is feasible. Code isn’t, and shouldn’t be, forever, but it should be dependable.

And if you’re on the other side of the equation, making use of a shared API or service, respect the obligation to use the service wisely. Make sure you’re using the service in a reasonable way, without over-taxing it; if you require additional scalability, try to work with the service’s owner before you start to make extreme use of it. I’ve had web services die because they were forced to respond to a multi-threaded, distributed system when they were originally designed to handle a simple queue; it’s not much fun to fix that sort of problem after the client has already gone into production.

If you’ve already built your applications to be trustworthy, the next obvious step is to extend that trustworthiness over time into code that earns the loyalty of other applications. Respect the implicit contracts between components, and perhaps you’ll help to nudge us toward respecting the implicit contracts between people, too.

Additional reading:

• Contracts, Scenarios and Prototypes: An Integrated Approach to High Quality Software
• Test Driven: TDD and Acceptance TDD for Java Developers

One of the hats I wear besides “programmer” is “Scout leader.” I’ve got a Cub Scout den of a dozen Wolf Scouts, and I serve as our Pack’s Assistant Cubmaster. It’s a side job I do because (a) I love my sons, who are enthusiastic Cub Scouts, and (b) I came up through Scouting myself: my father and grandfather were both Cubmasters, and I earned my Eagle in 1984. The basic life lessons of Scouting, especially the twelve points of the Scout Law, are about as succinct and universal a code of ethics as you could ask for. ¹

This is the first of a series of posts exploring how the twelve points of the Scout Law–a Scout is trustworthy, loyal, helpful, friendly, courteous, kind, obedient, cheerful, thrifty, brave, clean, and reverent–can be applied to information technology in general, and programming in particular. It will likely be a somewhat irreverent look–I also subscribe to the notion that a Scout has fun–and, I hope, useful, whether you’re a Boy Scout Programmer or not.

If a scout says “On my honour it is so,” that means it is so, just as if he had taken a most solemn oath. Similarly, if a scout officer says to a scout, “I trust you on your honour to do this,” the Scout is bound to carry out the order to the very best of his ability, and to let nothing interfere with his doing so. If a scout were to break his honour by telling a lie, or by not carrying out an order exactly when trusted on his honour to do so, he would cease to be a scout, and must hand over his scout badge and never be allowed to wear it again.

Robert Baden-Powell, Scouting for Boys, 1908

Trust is generally hard to come by these days, especially in the business world. Every word that comes from management or analysts or consultants has to be parsed and weighed and heavily salted; plain talk and honest dealing are quaint notions in these brutal times.

While I think that much of our current discontent could have been avoided if there had been a few more Boy Scouts in MBA programs, there’s not much that we programmers can do to affect the moral compass of a system that’s trying to navigate without a needle. But maybe we can look inward a bit, and consider ways in which we could be a bit more trustworthy ourselves. I’ve got one small suggestion that may not shift the economy back onto a moral footing, but might help developers sleep better at night.

Do in your code exactly what your code says it will do; no more, no less.

Not long ago, I was refactoring some old (circa 2001) code. It was a Lotus Notes application with a web interface that used the Sun LDAP APIs to manage some LDAP nodes. It was one of my first Java applications–at the time, Java was the only option if you wanted Notes and LDAP to communicate–and it showed in more than just the way I handled string buffers.

The object model was a little over-complex, but workable; the encapsulation was pretty awful, exposing the application to a little too much of the specific LDAP implementation to make it very portable. But the worst thing by far were the side effects.

I had the basic understanding of “getters” and “setters” from my Java crash course, but I didn’t understand how to keep them away from each other. Too many of my “getter” methods inadvertently called a “setter” method (or, worse, manipulated data internally, in great big blocks of unreadable nested “if” statements). You’d think you were innocently asking for a piece of data from LDAP, when unbeknownst to the calling method you were actually writing a whole tree of nodes. Yuck!

The error handling was pretty awful, too. The methods either threw esoteric LDAP exceptions, or caught generic java.lang.Exception objects, or swallowed their errors and just kept chugging. From the outside, you really had no way of knowing if something worked (even if you could figure out what that something really was).

The first thing I did was pry the read/write functionality apart. The new public “get” methods did just that–they “got” data out of LDAP and returned it, either as primitives or simple objects, or as bean-like structures that were easy to understand. The public “set” methods prepared a bean that could be written, and the only methods that could actually modify data were named, surprisingly enough, “save” or “delete.” The side-effects were removed, so no one using the API could accidentally modify LDAP.

Cleaning up the error handling went a long way toward making the changes trustworthy. Note that Baden-Powell says that a Scout does his task “to the very best of his ability,” not that he succeeds every time. There are vagaries–network, memory, fire, flood–that even the best application can’t handle, and plenty of contingencies that any application can predict. Rather than trying to soldier on when things fail, know when to report back a useful error and stop the application from damaging your data. Subclassing the correct exceptions, setting useful error messages, and warning the API user what kinds of problems might arise so they can handle them appropriately makes your code worthy of trust.

The interesting thing about this exercise was that the trustworthy code–the code that did just what it said it would do, no more and no less–was lighter, simpler, and more portable than the overly complex code that I started with. It ran faster, too. One could say that this was because of better OO design and six or seven years of hard-won experience, but I think it was because it adhered first to B-P’s core principals.

¹By universal, I really do mean universal. I disagree strongly with the current BSA policies excluding gay and atheist/agnostic Scouts and Scouters. If you’ve got a passion for working with kids, a willingness to spend hours sanding Pinewood Derby cars or tying knots, and an enthusiasm for helping boys grow, then I want you to be a Scout leader. If a kid is prone to questioning things, exploring the meaning of life, and honestly grappling with the path to adulthood, then I think Scouting is a safe, supportive, and fulfilling place for him to do it. Questions of doctrinal belief and sexuality simply don’t enter into the day-to-day efforts of running a successful Pack or Troop. Scouting in America survived for almost a hundred years without such tests and exclusions, and I’m confident that in time we’ll move past the current policies.

I’d also note that I simply can’t square the BSA’s policies with the spirit of the Scout Oath and Law. In Baden-Powell’s original formulation, “a Scout is a friend to all, and a brother to every other Scout.” That doesn’t leave a lot of wiggle room for discrimination.

Back to top

The programmer needs lots of tools to succeed: IDEs, compilers, text editors, debuggers, and various other software geegaws and doodads.  We’ll talk about some of these in upcoming posts.  But the most important tool, and the one too often overlooked, is social capital.

This is a challenge for many of us: let’s be honest, there’s a lot of truth to the stereotype of the soically-awkward computer geek.  Most of us, if given the choice, would love to spend our days heads down, working on code,w ithout the messiness of human interaction.  Unfortunately, that’s not a choice that many of us have.  Whether in a large shop or small, we need to interact with a wide array of people to get our work done.  Customers, testers, DBAs, system administrators, managers … Our code goes nowhere, and does not good, unless we’re able to work across all the IT and business disciplines.

There are good ways to work with people, and bad ways.  Most of us are good at the bad ways: standoffishness, obtuseness, and one-upmanship come naturally.  These are all good ways to burn social capital to no good end.  So here are a few ways I’ve found of building social capital instead, which you can then spend in more useful ways.

Offer to Help

Do you know something your co-workers don’t, that might help them with their projects?  Share it.  Even if their problem has nothing to do with your project, the insight will be appreciated if offered humbly and with no quid pro quo.  You’ll build a reputation as an expert, and generate goodwill, with even the smallest bits of help.

Ask for Help

More even than offering to help, asking for help builds social capital.  People like to feel smart, and like to be helpful, even the curmudgeons.  This can be a great way to mentor junior colleagues: rather than pontificating on your way of doing something, involve them in the solution process and ask for their insights.  They’ll learn by teaching, feel like an equal member of the team, and may surprise you with their skills.

Share the Credit

Give credit where credit is due. In most IT operations, many hands go into creating success; when the spotlight lands on you, acknowledge the help you received. Sharing credit is a good way to bring a new team member on board, and to repair the bridges that often become a little rickety between IT teams.

Take the Blame

“I didn’t do it. Nobody saw me do it. You can’t prove anything.” It’s funny coming from Bart Simpson, but not so funny from an IT professional. Odds are that someone did see you do it, or can prove it, unless you’re especially good at covering your tracks. So your best bet when you screw up is to take the blame and make amends.

One of my biggest screw-ups happened about three weeks into my job as a Lotus Notes developer. I made some changes to our mail purge agent to support calendering and scheduling when we upgraded to Notes 4.6; I didn’t have any test data older than the purge window, so I commented out the “purgeDays=90″ line and replaced it with “purgeDays=14″. Of course, I failed to switch back before the change went into production, and the hungry agent began chewing up an extra 76-days worth of e-mail. I had quite a welcoming committee waiting for me in the morning…

By admitting to this colossal blunder, I was able to salvage a little bit of my pride and also got the opportunity to learn, over the next week, a lot of things about tape backups, Notes replication, and mail server administration, and had the lessons of code review and good testing practices drummed into my head. Had I tried to dodge the blame, I would have ruined my relationship with the Notes administrators and, no doubt, I’d have started on a new job search.

Not every work environment is so forgiving of screw-ups; ‘fessing up may be a quick route to an exit interview. But that may not be so bad, either, even in economically grim times; do you really want to work someplace where honesty is so badly rewarded?