In the article he discussing some of his favorite features of SlickEdit and why SlickEdit is his code editor of choice for programming.

On objections on switching editors

If your current editor works well enough for you, why switch? The answer depends on how you define “well enough.” Your current editor probably handles every editing command you think you need now, but consider the possibility that something could make you far more productive. You’ll see a few examples in a moment, but first, here are some of the reasons you might decide not to switch editors.

Regular Expression Search and Replace

This isn’t an exclusive SlickEdit feature, some other editors have it too; but if you haven’t had the opportunity to experience regular expression searches, you should really consider switching to an editor that supports the feature.

Macro Record/Playback

SlickEdit carries out many of its commands through its slick-C programming language (note that both Brief and Emacs have their own languages as well). SlickEdit lets you write your own macros, or do a simple record / playback. This comes in handy when the syntax for find and replace gets too dicey.

Other Features

As you might imagine, because SlickEdit’s been around for 20 years, this article just scratches the surface.

Continue reading Hey, Check Out My Slick New Editor! here: http://www.devx.com/enterprise/Article/42874/0/page/1

SlickEdit’s Slick-C macro language should be no stranger to our users, but many folks aren’t aware that macros can be called when SlickEdit is started. In this tutorial, I’ll demonstrate how to use Automator to create a simple text service for SlickEdit, using this macro call facility.

First, launch the Automator application and create a new service using the Service template. At the top of the new workflow, it should say Service receives selected text in any application. Make sure Replaces selected text is not checked.

From the library’s actions panel, select the Text > New Text File action, and drag it into the workflow as the first item. Pick a name and location for the temporary file to be saved, and make sure Replace existing files is checked, or else you’ll receive an Automator error the second time you use the service. Select the Encoding to be (UTF-8).

From the library’s action panel, select the Utilities > Run Shell Script action, and drag it into workflow as the second item. The shell should be set to the default of /bin/bash. Change the right-hand drop-down to read Pass input as arguments.

Delete any existing text in the shell script editor. Add the following text as the first line.

export VSLICKXNOPLUSNEWMSG="1"

Switch to Finder, and navigate to the Applications directory. Highlight your SlickEdit application, and Control-Click the application, and select Show Package Contents from the context menu. Drill down to the Contents/slickedit/bin, highlight the vs executable, and drag this into the shell script editor. This will insert the full path to the executable in the script editor. Make sure it’s on a new line after the export line you just typed.
Append the following right after vs, making sure the command is all one line.

-#new-file "-#get $1"&

The full script should look like the following:

export VSLICKXNOPLUSNEWMSG="1"
/Applications/SlickEditV1402.app/Contents/slickedit/bin/vs -#new-file "-#get $1"&

Automator Service

Don’t forget the ampersand at the end of the second line. Save the service, (⌘+S), and give it the name “New SlickEdit File”.

Switch to another application, like Safari or TextEdit, highlight some text, and pull down the application’s services menu. Your new service should now be available in the menu in the Text category.

The SlickEdit “magic” is done with the -# arguments. These specify macros to be called when SlickEdit in invoked. Any SlickEdit macro command (defined with the _command keyword in Slick-C) can be called. Surround the entire -# argument with quotes if the Slick-C command takes any parameters, like the get macro in this example.

You can create a similar service that will insert the text into the currently active document by simply removing the -#new-file argument.

By default, service workflows are saved under $HOME/Library/Services. You can remove the service by removing this file.

To rename a Service, select the workflow file under $HOME/Library/Services, Control-Click to bring up the context menu, and select Show Package Contents. Look for the Contents/Info.plist file, and open it in the Property List Editor application. Change the value of the Services/Item/Menu/Menu item title entry. You do not need to rename the workflow file itself.

Boy: Mr. Turtle, how many licks does it take to get to the Tootsie Roll center of a Tootsie Pop?
Mr. Turtle: I’ve never even made it without biting. Ask Mr. Owl.
Boy: Mr. Owl, how many licks does it take to get to the Tootsie Roll center of a Tootsie Pop?
Mr. Owl: Let’s find out. A One… A two-HOO…A three.
(crunch sound effect)
Mr. Owl: Three!

This illustrates two common problems in oral communication. The first is the iterative process of finding someone who might know the answer to your question. In software development, the questions are typically of a more concrete nature, relating to a specific design or implementation choice.

Most software projects depend on a great deal of local knowledge. This is knowledge that is specific to the project, something you couldn’t know prior to working on the project. This include things like architectural and design details. The local knowledge is rarely written down in an organized manner but is contained in the collective experience of the development team. Because it isn’t written down and cataloged it cannot be searched, except through the iterative query process.

The other problem that this commercial illustrates is that of false experts. Like Mr. Owl, you will find people who will give you a definitive answer but one that is, unfortunately, wrong. In software development, it can be very difficult to spot these wrong answers–you don’t get to see someone just bite into the Tootsie Pop to come up with it.

In some cases, the person may truly believe the answer they give, and we’ll assume that until we have proof to the contrary. At other times, people just don’t like to admit that they don’t know something. So, they make up an answer. In either case, the damage to your work is just as bad.

Folklore is typified by this kind of oral communication. It is the main method for communicating important information in primitive cultures. Knowledge is passed from one person to another. Often, because of miscommunication, the knowledge is corrupted by each successive telling.

It’s like that party game where you start off with a sentence and have each person whisper it to another person. This is repeated several times and then the last person writes down the sentence. In the end, the meaning of the sentence is often radically changed with comical results. The same thing happens in software development, but the results are far less comical.

The solution to both of these problems is to document local knowledge. One form of that is code comments. So much has been written on that topic, that I don’t feel the need to add more. However, many things are not appropriate to store in code comments. It’s that kind of knowledge that is most often passed along as folklore.

Fortunately, technology has given us a solution. A wiki provides a centralized knowledge repository that is edited by the group. This allows for the information to be easily reviewed for accuracy. It also eliminates the need to wander around and find someone who might know the answer to your question.

It also addresses another problem. Many people are hesitant to go ask questions. Either they are afraid of looking stupid, or they don’t want to trouble their coworkers. So, they will often flounder around trying to figure it out on their own, wasting time, or they will try to make due without the answer. A wiki allows people to find an answer without the potential embarrassment of exposing their ignorance.

To be successful, a wiki needs to be searchable and browseable. The search capability is needed to find the answer to specific questions. Browseability allows someone to view a set of topics and delve deeper to get more information. This is important to allow someone to gain the initial knowledge on a topic, particularly for getting new team members up to speed. Most packages do a good job providing the search capability. But very few provide a good mechanism to build a browseable knowledge structure.

At SlickEdit, we use MediaWiki for our shared knowledge. It provides both an excellent search and a convenient means to organize topics. The side menu allows you to structure your top-level categories, and each page automatically includes a table of contents if it contains 4 or more subsections. This makes it simple to build a logical knowledge decomposition. It’s this capability to create a browseable structure that sets MediaWiki apart from other wiki software we tried.

Finding the right wiki software and setting up an initial structure is only the first step, though. The main challenge is getting the team to populate it. You face a couple of common problems here.

The first is the normal reluctance of programmers to document things. Many programmers despise any activity that is not directly related to producing code. This is a tough nut to crack, since this attitude is often deeply ingrained in the developers psyche. How you overcome this depends on the person and the arguments that they will listen to. You can appeal to their sense of professionalism and explain that this is part of professional development. You can appeal to their sense of teamwork and explain how this helps make the team more effective. You will need your full set of management skills to get everyone contributing.

Even if everyone is willing to contribute, one problem that often prevents a wiki from reaching its true potential is that of obviousness. Once you know something, it seems obvious to you. If it’s obvious, then why document it? This same problem plagues code comments. The best solution is to make the wiki an essential part of the problem solving process. When someone is trying to answer a question, they should look in the wiki. If they don’t find the answer, they should make a note to come back and add this information to the wiki after folklore has delivered an answer.

So, how does having a wiki alter the scenario depicted in the commercial?
Boy: Hmm, I wonder how many licks does it take to get to the Tootsie Roll center of a Tootsie Pop?
(Boy looks in wiki for the answer and finds an entry by Mr. Owl: “How many licks does it take to get to the Tootsie Roll center of a Tootsie Pop? Three.”)

Well, at least he didn’t have to go bother curmudgeonly, old Mr. Turtle.

In terms of economic stimulus, this could have a much greater effect on the nation. Consider that many programmers use minimalist editors that provide little help to analyze and navigate their code, don’t include powerful completions, or features to cut the number of keystrokes necessary to type their code. If these programmers switched to a more powerful editor, like…oh, let’s say, SlickEdit…their productivity would go way up.

As the productivity of the individual programmers goes up, their projects would get done earlier or include more capabilities. This increases the productivity of the people using that software, which would then increase the profitability of those companies. Since software underlies almost every industry, this could lead to a potential boom, the likes of which hasn’t been seen since the post-WWII expansion. Suddenly, there’s a surge in the US GDP. We pay off the national debt in a few years and have money left over for a comprehensive public health care system.

And it all begins with getting people to switch to a more effective editor.

Unfortunately, SlickEdit isn’t big enough to warrant a special government program like this. We’re not one of those too-big-to-fail kind of companies. But that doesn’t mean you can’t experience your own little economic stimulus.

Look at your coding practices and see if a more powerful editor wouldn’t help you write more code faster with fewer errors. Though the government won’t pay you for switching, the boost in productivity surely will.

SlickEdit is Giving Cash for your Clunky Editor!
Cash for Clunky Editors Program:

If the editor you purchased is lacking the speed, power, and flexibility SlickEdit provides…trade it in for CASH towards SlickEdit.  Call 1-800-934-EDIT (3348) or email sales@slickedit.com, and mention the Cash for Clunky Editors Program to learn about the savings.

The program expires on September 30^th, 2009, so act quickly.

Happy coding,
The SlickEdit Team

1. those with open and honest communication
2. those whose communications better resembled Soviet-style propaganda

As a manager, I’ve always considered accurate information one of my most important assets. I need to know where we are and what it’s going to take to succeed. My team has standing orders to let me know as soon as they figure out that they’re not going to make it so we can adjust the plan.

I’ve always been surprised when the people I have reported to didn’t share this enthusiasm. As managers, our chief responsibility is making effective decisions to achieve the stated goals. How can you possibly do that in an environment that doesn’t encourage people to speak the truth?

On one project, we developed the following phrase to report statuses, “I know of no reason that the project won’t be completed on time.” While most of us had serious misgivings about the plan, anytime someone voiced those concerns their manager would grill them like Perry Mason trying to get a confession. In the end, you really can’t prove that things won’t get done on time, so why get worked over for nothing.

This predilection for denial showed up when we were asked to build a new capability in about 3 months. I did some analysis and determined that it couldn’t be done and that it would take more like 9 months. My manager wasn’t happy with that estimate, so he asked some other developers. One said he could do it, which vindicated the manager and made him happy.

After 3 months, the project was starting to come together, but the core of it still had a lot of work left. So the developer told the manager that he needed a couple more months. The manager, really needing this to get done, granted the extension. That cycle repeated itself a couple of times until, in the end, the project took about 9 months to complete.

You would think that the manager would be upset at a developer who so seriously underestimated the amount of work needed. Instead, he was roundly praised for his can-do attitude.

It takes courage to speak the truth, particularly when it is an unpopular truth. Likewise, it takes courage to be willing to hear the truth, since it will often conflict with your own beliefs and desires. Being willing to speak and hear the truth has always been the hallmark of the best companies for which I have worked.

The basic reason for this is that each feature was written in isolation without finding and reusing the capabilities of the other features. This is a very common problem on most software projects. To address this issue, I believe that software development should be broken down into two different workflows: mechanism application and mechanism creation.

We can define a mechanism as a component with a cohesive set of functionality, like the wheel. In most cases, mechanisms are meant to be reusable, though it is possible that there will be only one use for that mechanism in a particular program. Common mechanisms in software include login processors, calendar widgets, and sorted lists. These elements perform a specific function that is independent of what they are used for.

Mechanisms can also be specific solutions to common design problems, like error logging, object persistence, and thread synchronization. Ideally, these would be encapsulated in a library that is used by other developers, but in some instances it is more a matter of following a specified convention.

For example, one project I worked on specified that each function would contain #ifdefs for tracing and logging with specific information that each function should output. This still represents a mechanism that defines a cohesive functionality, in this case, tracing. But instead of writing a reusable library, the mechanism was primarily a set of conventions we all followed when writing our functions.

During mechanism application, the specialized functionality of a feature is built using existing mechanisms. You can work on your own unless you have a question about the specs or need assistance from another developer. The code being written is unique to the feature, so little attention is given to reuse unless a new mechanism is needed. Then you enter mechanism creation.

During mechanism creation, you are developing a generalized capability that is specifically intended to be reusable. This requires a totally different workflow. You have to stop and do a degree of analysis before you create the new mechanism. Several questions need to be answered. Are you sure there isn’t already a mechanism for this? If not, what are the essential behaviors of this mechanism? Where should it be stored?

These questions are best addressed with other members of the team. The goal is to produce a mechanism that can be used by everyone, not just by you. So, you need to get their input to make sure it does more than meet your immediate needs, or at least doesn’t prevent someone from extending it in the future.

When a developer tackles the new mechanism as part of their normal development, two common problems occur. Often the programmer includes the mechanism as part of the feature-specific code, rather than placing the mechanism into the library where others can find it. Even when they do put the code in the proper place, it often is written in such a way that it is only useful for this feature. You can’t make it reusable without breaking the feature that already depends on it.

In most applications, mechanism application is very straightforward, simple programming and requires little creativity. Mechanism creation, on the other hand, requires a great deal of creativity and design effort. You have to think more about algorithms and efficiency.

So why don’t programmers naturally break their work into these separate workflows? I think there are a number of explanations.

First, I think programmers get very focused on completing a feature. If they have to interrupt that work to enter the slower and more deliberate workflow required to create a new mechanism, then it delays the attainment of their goal.

Secondly, programmers like to program. Designing reusable components requires meetings, documentation, and reviews–all of which get in the way of programming.

Thirdly, most programmers aren’t too keen on collaboration. When you talk things over in a group, you have a chance of not getting your way. If you just build it yourself, you can do it the way you think it should be done.

Finally, by separating the two workflows, the creation of a needed mechanism might be assigned to a different programmer. Since the creation of these mechanisms is often more challenging and, therefore, more fun; developers are hesitant to initiate a workflow that would potentially deprive them of this fun.

Basically, it’s more fun to reinvent the wheel than to determine whether a suitable wheel already exists. If the wheel does need to be invented, it’s less fun to do it with a committee of your peers who may disagree with your vision for the wheel.

This was the case when we put out our first release of SlickEdit 2009, version 14.0.0.5. We had completed our usual beta cycle before releasing this version, which included a number of drops to correct reported problems. After the last beta drop, we made a few more changes, all of which seemed totally risk-free.

Within two hours of releasing SlickEdit 2009, we had reports of severe problems with the File tabs and the File list. These problems trace back to one of these simple, risk-free changes. We had done our normal testing after these changes, and we hadn’t discovered any problems. But this problem was so severe we had to pull the release until it could be fixed.

So, what did we learn from this?

First, there are no small changes. Even when you think you know the effect a change will have, you could be wrong.

Should we have tested more? Sure, you can always test more, but that is no guarantee that you will find a problem. Testing suffers from a horizon effect: you can only see as far as you test. The problem you need to find could lay just beyond or miles beyond. You don’t know until you find it.

Second, testing is different than using. When you are testing, you click all the buttons and try all the functions, but you are rarely able to perform all combinations of operations. Some problems depend on the order in which operations are invoked. Others require multiple operations before the problem surfaces, as was the case with the problem we missed.

It should be no surprise that the parts of SlickEdit that work the best are the things we use everyday. But there are many languages we don’t use on a daily basis. Even if we did, with a product like SlickEdit, our testing cannot hope to replicate the variety and complexity of our customers’ use patterns.

We’ve determined that prior to shipping any release, we need help validating it. So, we’ll create a Release Candidate when we have finished our testing. We’ll make the Release Candidate available for early adopters to test, and if all goes well, it will be used for the General Availability release. In this way, we hope to catch more problems before they are set free to roam the countryside and terrorize the populace.

Q&A

Does that mean you’ve given up on testing? No, we plan to continue testing just as we always have. We just need help with final validation.

What if I don’t have time to help you catch problems? Then wait until a release is no longer a release candidate. At that point, others will have helped to validate it, and you will have less likelihood of experiencing issues with a new version.

If an unladen swallow flies west from New York…

• The next_sexp (Ctrl+Alt+Right) and prev_sexp (Ctrl+Alt+Left) commands can be compared to next_word and prev_word, except that they treat blocks as words.
•  The backward_up_sexp (Ctrl+Alt+Up) command is the shortcut for navigating to the start of the immediately enclosing block (in Lisp, this would be the open paren).
• The forward_down_sexp (Ctrl+Alt+Down) command is used to drill into a block. If the cursor is at the start of a block, it moves the cursor to the first S-expression within the block; otherwise, it behaves like next_sexp.
• The commands select_prev_sexp (Ctrl+Alt+Shift+Left) and select_next_sexp (Ctrl+Alt+Shift+Right) extend a character selection from the cursor position to the start of the next or previous S-expression, respectively. Like the Shift+Cursor commands do to CUA style selections, if executed repeatedly, they will extend the current character selection.
•  The cut_prev_sexp (Ctrl+Alt+Backspace) command will delete the S-expression to the left of the cursor and copy it to the clipboard. Again, if called repeatedly, this will prepend the subsequent deletions to the clipboard.

The let down happened when I started thinking about the content of what I’m reading now versus what I was reading about 5-10 years ago.  Blog content is great, but it’s like reading a newspaper that’s nothing but a big editorial section.  Most posts are packed with unfiltered content that often falls into one of two categories; “You know what I think?” and “This is cool, check this out!”.   Both types of blog post are great and I’ve spent many, many hours reading these.  When I really thought about the content I’m reading though, I realized that I’m actually learning a lot less than I used to.  That wasn’t the only problem either.  Reading primarily in the browser has turned me into a skimmer, something I rarely used to do.  There’s so much pure bloggage out there that you have to skim and filter what’s worth reading and what’s not.  While that’s not awful in itself, I’ve noticed that I tend to retain a lot less when I read this way.  I also found that reading the blogs was only half of the reading I was doing.  The rest was reading people’s comments about what I had just read.  I can easily spend more time reading that than reading actual blog content.

At some point in your life, you say things or do things that make you think to yourself, “I’m really getting old.”  Everything is turning digital now.  Do I sound old yet?  In addition to programming, I’ve been a photographer for a long time, almost thirty years.  I started back in high school doing black and white film and eventually built a darkroom in my house.  About three years ago, I realized that buying film, paper and chemicals and spending countless hours in that darkroom could be replaced by spending a fraction of the time, at no cost, in front of my computer with Photoshop.  It was a sad realization, but I moved on to a digital SLR and turned the darkroom back into the original walk-in closet.  The only thing missing from Photoshop is actually feeling the film and the paper.  It may not sound like much, but after so many years I can say that those things are significant.  There’s something about handling the materials that puts you in touch with the process, and I haven’t found a replacement for that yet when I “develop” my photos the computer.

Reading is the same way.  There’s something about sitting down with a book that puts you in the mode of committing to read.  I can’t browse away from what I’m reading in a book with the click of a mouse.  Actually opening the book, holding it in my lap and turning the pages makes me feel like I’m ready to learning something new.  This is all about the experience of reading, and retaining what you read, without distraction.  It’s the same reason I wasn’t allowed to do my homework with the TV on when I was in school.  I can say for sure that I retain more when I read a book than when I read a blog at the computer.

Most computer books are also directed at actually teaching something.  Whether it’s a book about a programming language, a way of approaching design, or how to see a development project through to completion, most books teach.  However, it’s a rare occasion when a blog post really teaches you something.  Opinion pieces are great and have their place, but when the scale tips from spending time reading books to reading blog posts, you’re also tipping the the scale of how much you’re learning.

So now you’ve read a blog post about why you should try to read less blog posts.  You should probably eat more green vegetables and get eight hours of sleep each night, but I’ll save that for another post.  I’m going to try to make a change in my blogging, and do more writing that leaves readers with something more useful than a simple conversation piece.  Until then, try turning off the browser and go pick up a book… the trees will forgive you.

To display the window, from the main menu, click Tools > Regex Evaluator. Enter some sample text in the top area. Select the type of regular expression syntax to use, then enter your expression pattern in the bottom field. Matching patterns in the test case are indicated with a wavy underline. Groups (tagged expressions) are indicated with a boxed yellow highlight.

SlickEdit provides an emulation mode for the Vim text editor. If you want to learn Vim, or need to hone your skills, you can use the vimtutor command. Most Vim installations come with this command, which displays a special “learn-by-doing” practice file in the editor that you can can actually edit as you learn how to use the Vim commands. This file has been customized for SlickEdit users.

To use the command, open the SlickEdit command line, then type the command and press Enter. The practice file is displayed in the editor. Each time you use the vimtutor command, SlickEdit creates a fresh copy of this file.

Tip

Blueprints

One of the first things I noticed was that whenever I walk past the area where the construction guys are working on, there are always blueprints around.  Serious blueprints, not just stuff scribbled in a notebook.  Someone had taken the time to document in great detail every angle and aspect of even the most boring places in our office.  How often have you ever seen such blueprint level detail in software design documentation?  It’s rarely done, and if it is, it’s rarely maintained.  There are many times when I wished I’d just done the work of writing down my thoughts as I coded, so that if I needed to revise that code in the future, I’d have a blueprint of what was there.  It’s obviously important enough for the construction workers to insist on, why not software engineers?  Most of the code I’ve ever seen or worked on is barely commented, let alone designed or modeled.

Diff, undo and revert

Of course, for construction, having the blueprint level of detail is essential.  For them, there is no Undo command.  If you’re cutting drywall and you saw through a main electrical line or cut a key structural support, there’s no way to easily fix that problem.  If there’s one thing I learned from watching “This Old House”, it’s that when you build something, you measure twice and cut once.  For us software developers, we have a whole arsenal of life saving techniques.  Diff, undo and revert are all things we do when we’ve gone down the wrong path.  I joke sometimes that I wish everything in life had an undo command.  Unfortunately, these things have also made us lazy (there, I said it).  Diff, revert and automated refactoring have caused many software developers to stop measuring at all before cutting.  Admit it, if compiling refactored code could potentially cause the roof to collapse, we’d be a lot better at verifying correctness by:

1. Reading documentation and notes written by other developers whose functions and classes our code relies on.
2. Documenting the functions and classes we write so that others will use them correctly.

These are easy things to do that can potentially save a lot of time in future coding work.

Frog in the Well

There’s a riddle about a frog trying to get out of a well who can jump up three feet, but then falls back two feet.  The more times you cut without measuring, or edit without designing, the more you increase the chance that you will make the wrong cut.  For construction workers, making a wrong cut is absolutely disastrous.  For software engineers, making the wrong cut means backing out and trying again.  It’s easy to forget that there’s a cost to reverting and refactoring; the time you spent writing what is being undone.  I’ve known software engineers that program like the frog trying to get out of that well.

Being able to back out of changes is a luxury that shouldn’t be taken lightly. There will always be times when it’s necessary, but it’s important to understand why it’s necessary.  The next time you have to revert or refactor, ask yourself how much time you lost writing the original code that had to be changed.  How much time could have been saved by designing the code before writing it.  How much time will be lost in the future if you don’t document why you had to revert or refactor?  If you wrote some code that you realized later was a mistake, what will keep other developers from making the same mistake in the future?

Don’t be the frog in the well.  Take a tip from our friends, the construction workers, and provide a plan for the code you intend to create or restructure.  Put it somewhere where everyone can get to it, and finally, tell everyone it’s there.  Not only will you benefit from the fore-thought of your design, but other developers will benefit from your insight before working on the same code.

Hopefully, you could hear the sound of sarcasm dripping from each word in that sentence. I don’t know anyone who looks forward to annual reviews. As a manager, I dread this more than others. Not only do I get to have my own review, but I get to do the review for all of those who report to me.

I have to say that doing annual reviews falls somewhere between performing a root canal on myself and suffering through reruns of “Little House on the Prairie”. I know that seems like a broad area of pain, unless you hate that show as much as I do.

The chief reason for this angst is that no one, it seems, is ever happy with their review. Maybe that’s a good sign that I’m taking the process seriously and trying to really evaluate my team members’ strengths and weaknesses. Maybe that means I’m an overly critical [insert epithet here]. Believe me, nothing would be easier than telling everybody that they rock and just send them back to their cubicles.

I can’t bring myself to do that, though. I have to try to make this a meaningful event. To grow, everyone needs to know where they are strong and where they are weak. How many people realistically have no areas they cannot improve on?

Aside from the discomfort of doing an honest assessment of someone, the biggest problem in most review systems is that the scores are arbitrary and meaningless. At most companies, there is no effort to baseline scores or set a reasonable standard for what they mean.

At one company, we used a complex review system with 16 different ratings in 5 areas. Each was assigned a value from 1 to 10 with a 10 being the best score. When I had finished the reviews for my team, most scores ranged from 5 to 10 with a reasonable bell-shaped distribution. So, 7 and 8 were far more common than 5, 6, 9, and 10. I later learned that another manager had simply gone through and given his people all 9’s and 10’s. Since the raises were tied to scores, his people got bigger raises than mine.

I could have saved so much time and so much aggravation by just doing the same thing. Obviously the company didn’t care. They never said anything to me that my scores were unduly low or that his were unreasonably high.

It makes me miss the simple scoring systems used in college. There you are given a course syllabus that outlines the structure of your grade. It shows what percentage of your grade will come from homework assignments and what percentage will come from exams. Where I attended college, scores were posted on the professor’s door. Not only could you look-up your score, but you could see your ranking among your peers. So, even if you got an 87 on a test, you might find that it was one of the highest scores achieved.

In the work world, you rarely have that kind of clarity. Some of your peers succeed on the basis of their social skills rather than their contributions. And even when you are given a rating, you have no idea how it compares to those of your peers. Is it any wonder that employees typically view annual reviews with suspicion and hostility?

So, to simply things this year, I propose a new system based on the Signs of the Chinese Zodiac . I got the idea from a placemat at a Chinese restaurant. There are 12 animals: Rat, Ox, Tiger, Rabbit, Dragon, Snake, Horse, Ram, Monkey, Rooster, Dog, and Pig. Each animal is assigned a set of characteristics both positive and negative.

For example, the rat is said to be “Forthright, disciplined, systematic, meticulous, charismatic, hardworking, industrious, charming, eloquent, sociable, shrewd. Can be manipulative, vindictive, mendacious, venal, selfish, obstinate, critical, over-ambitious, ruthless, intolerant, scheming.” (from Wikipedia).

The Chinese zodiac assigns an animal to each year, month, day, and hour. So, you can interpret your personality based on these animals and how they interact. The interpretation of these signs is very complex and subtle.

To apply this system to annual reviews, I would take the traditional approach of breaking down performance into key areas: communication, teamwork, leadership, initiative, job knowledge, etc. For each area, the manager assigns one of the 12 animals. Along with the reviews, the employees would be given a key, like the placemat, that lists all of the animals and their characteristics. Together the employee and the manager would discuss the interpretation.

“Well, Frank, you got a Monkey for Communication and Rat for Leadership. I’d like to see you bring these two into better harmony next year. You should strive for an Ox in Communication or maybe a Rooster.”

This would also help when employees compare their results. Yes, we know they aren’t supposed to do that, but in my experience those kind of corporate rules are no more effective than speed limit signs. Using the Signs of the Chinese Zodiac for reviews would eliminate any hard feelings over someone getting a better review.

“Jim got a Rabbit in Customer Focus and I got a Horse.” Walks away with a look of utter puzzlement.

This would also head off any arguments due to an employee feeling they got an unfairly low score. “Damn it, Scott! I can’t believe you gave me a Tiger in Judgment. You know I should have gotten a Ram!”

Yes, this would produce a review system that allows for the arbitrary results of most modern reviews while allowing each employee to find their own meaning in their scores. …and peace and harmony rang throughout the kingdom!

After three years of use it had developed its own unique personality.  It had the perfect background with cool sounds to match.  The fonts were just right.  All of the desktop icons were where I wanted them and I knew exactly where everything was off the Start menu.  I had scripts, shortcuts and bindings to do all the common stuff I need to quickly.  I’d gotten to know all of its quirks, traits, flaws and mannerisms over those few years.

However, like many computers, after installing several versions of many large apps, it wasn’t the playful, energetic puppy that it was back when I started using it.  It was in no rush when rebooting, and I could hear it let out a sigh whenever started Outlook or Visual Studio.  What were once speedy builds turned into mandatory coffee breaks.  Still, I loved that computer… we knew each other and wrote software together every day.

Then, early one morning, our sys admin came over to my office.  “It seems like your computer’s been trying to send out emails directly on port 25 during the middle of the night, any idea what that could be?”  I didn’t know.  We looked up the address where they were being sent, somewhere I’d never heard of before.  “Alright, I’ll bring over the Vista DVD,” he said.

And that’s when it sunk in.  An infection… a virus… the Vista DVD… I was going to have to reformat my machine.  I was going to have to shoot Old Yeller.

[From the movie... Old Yeller's gone rabid and Mama's holding a shotgun]
Travis: No mama!
Mama: There’s no hope for him now. He’s sufferin’. You know we gotta do it.
Travis: I know Mama… But he was my dog… I’ll do it.

I sat quietly for a while after he left, realizing that this was the end.  I spent the next few hours backing up all of my important files and exporting all of my preferences.  “There are automatic updates ready to install, reboot now?” it prompted innocently.  The poor thing had no clue.  I missed him already, and I wondered if a better place awaited him after fdisk.  A place without disk fragmentation, bloated installations, useless polling auto-update tray apps and frozen taskbars.  I said goodbye and shut down one last time before booting from the Vista DVD.

I’m still sitting at the same desk, but everything feels new and a little unknown now.  It’s like working again with that energetic puppy I began with.  He’s eager to start up and get to work, builds are a snap and the desktop is clutter-free.  I’m still getting to know it, and soon he’ll develop his own personality.  I still miss Old Yeller, though.

I worked as a contractor on one such project a few years ago. We were writing a call center application for a large enterprise client. The architect of this system convinced the client that the business analysts would be able to write in a high-level business language (invented by the architect) so that future changes wouldn’t require hiring programmers to modify the system. Each line of business script, it was claimed, had the power of 20 or 30 lines of lower level code. So, this promised even greater efficiency than just eliminating the programmer.

The business language had classes, constructors, destructors, and nearly all of the features of modern object-oriented languages. Maybe it started out as a simplified language that would be accessible to the business team, but it grew into the same level of complexity as the Java code we were writing to implement the rest of the system. There was no way that a business analyst without training as a programmer was going to be able to write effective code with this language.

Even worse, the programming team was struggling to write code with the language. There was no debugger or other tools, not even an editor with color coding. When you had an error, you had to determine if it was a bug in the script or in the interpreter, which was being modified almost daily.

Even if we accept that it is a worthy goal to eliminate the need for programmers, I don’t think it’s possible. That’s because programmers have skills and abilities other than just their knowledge of programming languages.

Whether this is by training or nature, I cannot say. Likely, it is a little of both. Programmers have aptitude in the skills necessary to succeed in our field and these get nurtured through practice. Regardless, I’ve noticed that programmers are often more capable in many ways than their non-programming coworkers.

Programmers think more logically. Working through if-then-else conditions is a core capability for any programmer. While working with business teams on requirements, I have often run across cases the where same ability was lacking.

During one project to develop an expert system for mortgage analysis, I was often given requirements for rules on how to handle loans with particular Loan-To-Value ratios or for a particular loan amounts. Not uncommonly, these requirements would have gaps. I’d have requirements for loans from $0 to $100,000; from $150,000 to $250,000; and for loans over $250,000. But there was a hole between $100,000 and $150,000. At other times I’d have conflicting requirements for overlapping ranges.

Programmers have a superior ability to analyze problems and come up with solutions. They excel at analyzing preconditions, sequences of events, and outcomes. Certainly, this is a key skill in programming, but it is also useful in troubleshooting and business case analysis.

Another key ability where programmers typically have an edge is the ability to make order out of chaos. I think that’s because the programmer is responsible for creating order within the program. We break systems into subsystems, subsystems into modules, and modules into units. There are no physical constraints that dictate the structure of the solution. Whatever order exists is created by the people who write the code. Reflecting on some of the codebases I’ve worked on, it’s clear that this is not a universal trait in all programmers.

While people typically think of programmers as coders, whose main talent lies in writing the arcane syntax of programming languages. I think that their main talent lies in their ability to analyze, troubleshoot, and solve problems. Code is just the physical manifestation that culminates the thought process of the programmer.

Let’s say that someone does manage to write a tool that allows people to define software and control its behavior without having to write code. The person using this tool will still need all of the other mental abilities of a programmer. If this were to happen, we haven’t eliminated the programmer; we just changed the job description a little.

Yes, I can envision a distant future where Artificial Intelligence is used to develop code—but that won’t eliminate programmers, either; it just ported them to a different platform.

Slick-C is a macro programming language upon which the SlickEdit code editor is based.  Slick-C allows developers to modify the look and feel of the editor, write macros to perform custom operations, add new language support, and essentially extend the editor’s functionality until it is completely customized according to your preferences.

From his first post:

Here you’ll find Slick-C macros of all kinds, from overly simple to fairly complex. I’m a writer/editor/journalist by trade, not a professional developer. Slick-C programmers should find something 0f interest here, including plenty of code that can be tweaked or fixed.

The purpose of this blog is to address the shortage of Slick-C code on the Web, while stimulating discussion and encouraging code sharing.

I’ve used Slickedit in my daily work since approximately 1998. Currently I have 388 _command macros in my vusrmacs.e file. I’m sure there are other Slickedit users whose macro folders are wishing to burst free and benefit the larger community.

My professional roles are technical writer; editor and researcher of print and electronic publications; desktop publisher; journalist. My programming experience has generally been limited to high-level scripting languages. I’ve spent a lot of time using numerous text editors and macro languages. Of the two kinds of Slickedit users named in the subtitle of this blog, I’m a Wordsmith rather than a Code Maven.

Regardless, I’ve grown weary of some wasteful pleasantries, and I’ve been trying to make things more efficient. In particular, I’m tired of saying “please” and “thank you” all the time, particularly with my wife. After nearly 25 years of marriage, haven’t I proven my love and respect? Do I need to continually show it through endless “pleases” and “thank yous”?

So, I asked her if she could just assume that every request I ask is automatically preceeded by a “please” and followed by a “thank you”. I mean really, if she expects one every time, why not just assume it’s there in the first place?

In programmer parlance, this would be equivalent to writing a macro. Macros are substitutions that are inserted inline so that the code is altered, as though the substitution were there all along. I won’t bore you with the syntax, but if you’ve used macros before then you know what a time-saver they can be.

Unfortunately, my wife didn’t go along with this notion. It appears that her ability to execute macros is substantially less effective than a C compiler. So, she still expects a tedious “please” and “thank you” for each request. Sheesh!

Some programmers have taken this notion of macros a little too far. From the many programmers I have worked with, I have noticed the following macros in use:

The Greeting Macro — this is a common one, where the programmer has fully eschewed any responsibility for saying “Good morning”, “Hi”, “How’s it going?” or any of the regular acknowledgements of the other person’s existence.

The “Yes sir, I’ll get right on it” Macro – with this macro, a programmer will no longer let you know that they have heard and understood your requests. You must infer that they will comply because they have ceased their efforts to make you feel stupid for asking.

The “No I don’t think you’re a complete moron” Macro – here, the programmer has given up with trying to smile politely and respect your opinion. The macro is intended to soften his critical and belittling demeanor. It is important to note the stress on the word “complete” in this macro.

The Personal Hygiene Macro – I know it’s boring to shower every day, but the rest of us really appreciate it. Trust me on this one!

please_and_thankyou(”If you enjoyed this article, leave a comment.”)

This is a great idea! Technology is so prevalent in our society and in our government that it’s impossible to conceive of a plan for effective government that is not based on a sound technology roadmap. Certainly, if we need a Secretary of Transportation, then we need a Secretary of Technology.

Making this a cabinet-level position will hopefully give the USCTO the authority to bring uncooperative agencies together. In truth, I think that will be the biggest challenge. Bureaucracies are rife with politics. They don’t like to be told what to do or to work with others. They want to do things their way without someone else suggesting a better way.

A Chief Technology Officer can be instrumental in setting goals and directions for our nation’s IT infrastructure. However, I have seen CTOs wreak havoc on organizations that were doing just fine without them. Here are a few common pitfalls I hope the new US CTO will be able to avoid.

Outsourcing Core Expertise

I have worked for years as a contract programmer, and I have worked for companies that provided outsourcing services. There are times when it truly makes sense to outsource. If you are not a software company, but you need to have software built, then you are generally better off hiring a company to do that for you. A company that develops software full-time will be far more successful than one with no experience.

For example, I worked for a company that developed workflow and routing systems that incorporated high-speed scanners. We had significant knowledge and experience with the hardware and issues involved with these systems. Our customers were companies that processed forms for things like book clubs or medical records. Those companies simply could not have built these systems as effectively as we could.

For them, the systems we built were just a tool. Their core knowledge was related to the business of processing the records. They just needed a system that made it faster and easier to process the information.

However, I have seen companies whose main revenue comes from selling software outsource the development of their products. Commonly, this is done by partnering with an offshore development house.

The problem with this approach isn’t that it’s overseas; it’s that the people working on the product do not work for the company. If you make money by building and selling software, then why would you ever want the knowledge necessary to create and maintain your products to be held by someone with no attachment to your company?!?

Cost Centric Management

Improving an organization is hard. It takes thorough analysis and creative thinking to find ways to do things better. Rather than finding ways to do things better, some CTOs try to make their mark by doing things cheaper.

Don’t get me wrong, I do believe that organizations should be run efficiently and that managers should be looking at costs to make sure they are in line. However, cost management is often taken to an extreme.

Examples of this mentality include hiring cheaper programmers rather than focusing on the knowledge and experience needed. Many companies treat programmers like interchangeable cogs with no appreciation for the difference between individuals. So, if they can hire programmers for $10K or $20K less per year, that’s a big win, right?

This mentality drives the offshoring approach. The lower cost is touted as a big win for the company, but little consideration is given to whether the product can be developed as successfully. This is particularly problematic if the development team is split, as is so often the case, with the business team working here and the developers working overseas. Software development has been shown to be far more successful when there is close interaction between the programmers and the subject matter experts, even more so with direct customer interaction.

Companies also attempt to restrict costs by scrimping on the tools they provide. We see that one a lot at SlickEdit. We often hear from programmers who want to buy SlickEdit but are told by their management that $300 is too expensive.

At SlickEdit, every developer has multiple monitors. We believe this is essential to getting your work done efficiently. I have worked at some companies where I bought my own equipment because they would not approve anything more than a single 17” monitor.

The fundamental mistake that drives these decisions is that they assume a fixed level of output. So, they believe they can cut costs and the output will not change. In truth, we know that the level of output in software development is highly variable and subject to many complex factors. The definitive work in this area is “Peopleware” by DeMarco and Lister.

Over Standardization

Standardization can be a good thing. When done properly, it ensures efficiencies of scale and the ability to dynamically manage resources within an organization. Standardization can be helpful to assist everyone in producing a similar result. If taken too far, it becomes a force to make sure that no one can achieve excellence.

No single tool or technology is good for all situations. The cost of trying to pound a square peg into a round hole can often exceed the cost of buying a round peg. You do have to guard against capricious choices (see Design Fail Patterns), but you should guard against a policy that is too rigid. Standardization should be a gravitational force that pulls towards a center, but it should not become an inescapable black hole

The larger the company, the more diverse their technology should be. Small companies may not be able to afford to dabble in different technologies, but larger companies can often see greater efficiency by allowing teams to select the right tools even when they are different. Further, by having a broader technology portfolio they reduce the risks associated with selecting a single technology, and they are more likely to discover new, more efficient ways of doing things.

“Vision”

I often see the word “vision” used with CTOs. They have “vision”. When I hear this word, I cringe. While having vision is often essential in succeeding, too often this word is used as license for narrow-minded, megalomaniacal tendencies that will brook no discussion or alternatives. Can you tell I feel strongly about this one?

Often the CTO forms this vision before they know anything about the organization. In my experience, the employees already know what needs to be done to fix most problems at the company. What they need is a management team that’s willing to listen. Instead, most employees fear going to upper management with problems and solutions.

Sometimes this “vision” is based on a success at a previous company. They see the new company as an opportunity to do what they did before. However, these successes are rarely repeatable. Organizations are just too different. Often, the reason a project succeeds is because of complex factors, not the least of which is the team that implemented it. Given the choice, I’d rather have the team from that successful project rather than one guy with the “vision”. Be careful how much credit you give managers (or any leaders) for the accomplishments of their teams.

Vision should provide an overall direction, a set of values that are used to balance competing needs. It should not be a totalitarian model to which an organization must conform.

I wish the new CTO of the United States much luck. It will be needed. Confidence in our government is at an all-time low. It will take much more than vision to change that.

For the sake of this discussion, we’ll treat defects the same as features. This isn’t totally accurate since some defects simply must be fixed as soon as possible. However, most defects are subject to the same decision process as features.

The Dictatorship

With this system, a single, all-powerful voice decides what gets done when. This is a common approach on smaller projects, where these decisions are made by the project manager. That’s not to say that this person doesn’t listen to advice from others. But when it comes time to decide they, alone, make the call.

Ultimately, the other systems typically have a single person who has to make the final decision. In my opinion, this is an essential characteristic of an effective organization. Everything should funnel up to a single person authorized to make decisions. People at different levels should be empowered to make various decisions, but in the end a single person should have the final authority. Otherwise, you flounder endlessly when a consensus cannot be achieved. It becomes a dictatorship when the leader ignores the advice and guidance of others and acts strictly on their own belief.

This approach only appeals to me if I can be the dictator, using my sagely wisdom to guide the product direction. In truth, this system can work well if the person in charge has a keen sense of what it takes to succeed. From accounts I’ve read, this is not unlike Steve Jobs’ approach to new product development. Though you can argue with his approach, it’s hard to question the results.

The Oligarchy

In an oligarchy , power is shared by small, elite group. This approach is often used on larger projects where various constituencies are represented. You might have representatives from project management, sales, development, quality assurance, and product support. In some cases, actual customer representatives might be involved.

The group meets regularly to discuss what is needed and when. Tradeoffs are weighed between features needed to spur new sales and fixes needed to appease existing customers. Typically, the group is lead by someone with final decision authority, but most decisions have a strong consensus.

This approach is certainly more representative, but it is also much more time-consuming. I’ve worked on projects that used this method, but they were very large with complex interactions between subsystems. Still, a light-weight version of this can be helpful to make sure all factors are weighed effectively.

The Democracy

In its purest form, this approach relies on votes from the masses to make the selection. Sometimes, members of the development team do the voting. In other systems, the customers are allowed to vote.

Though I cannot find a reference to it anymore, I recall that Sun used Duke Dollars as a way for developers to vote for specific fixes in the early days of Java. I’ve worked on teams where each developer was given some number of votes that they could apply to the bugs or features of their choosing.

I’m not a big fan of this approach. When the developers do the voting, this tends to favor the interesting, glamorous features over those that are more mundane. Often, these mundane features make a bigger difference to the customers. When the customers vote, they are typically guided by their own way of working. An effective product has to balance the different ways customers will use it.

You could use a hybrid approach, where the developers or customers submit votes but the decisions is ultimately made by a small group or individual. The problem with this is that it can be demotivating to the voters. If a feature with a high number of votes is rejected, they will ask why they even bothered. So, if you use a voting system, you should be willing to act on the results.

The Meritocracy

In the meritocracy , the best idea wins. Instead of suggesting a feature or voting for it, each feature is submitted with a business case. The business case is used to decide which changes make the biggest difference to the product.

This is my preferred approach to prioritizing features. It allows for input from all stakeholders and provides a means to assess priorities. With this system, anyone can challenge a feature and have it replaced in the schedule by demonstrating that another feature has a better business case.

Unfortunately, it is not always evident which idea has the greatest merit. So, this system relies on approaches from the others to make that call. A team or individual weighs the various proposals and picks the ones that best meet the business needs.

This approach also avoids the “squeaky wheel gets the grease” syndrome. Often, it is the customer or developer who is most vocal that gets their way. Great ideas languish because the proponent is not willing or able to be heard above the din of the highly vocal.

Truthfully, there are very few pure examples of any form of government. Most are a combination of these approaches. The most important characteristics of a feature planning system are:

• The ability to gather ideas from all stakeholders.
• The willingness to listen to these ideas.
• A system to evaluate ideas on their true merit.
• A clear vision of the product that helps to determine which ideas truly enhance the product and which just muddy the waters.

Of course, it wouldn’t hurt if we could somehow take humans out of the equation and have features selected by a race of benevolent and powerful robots. But that’s a post for another time.

Cast your mind back to the days of the tall ships, great wooden vessels that plied the oceans under wind power. Imagine one of those majestic ships sailing along when suddenly it hits a reef, tearing a large hole below the waterline. All hands scramble to save the ship. They bail and bail, but the ship continues to sink. As the ship sinks lower, they bail more furiously until finally the ship is lost. The survivors are washed ashore on a nearby island.

As they stare out at the masts of the ship, still visible above the waves, the Captain asks, “Why weren’t we able to plug the leak?”

One of the crew pipes up, “Captain, sir, we were too busy bailing to plug the leak.”

OK, this is a contrived example, and it’s very hard to believe that it could occur in real life. However, very similar situations frequently arise in software development.

Bad Codebase

The most typical way I’ve seen this occur is on projects where the early work has set us up for failure. The infrastructural code is so full of bugs or badly designed that it has become a stumbling block to get the rest of the system built. The team furiously pounds away at the code, driving toward a critical milestone fixing bugs as they can. But with every iteration, things take longer to do and the codebase gets harder to work with.

In this case, the leak is the poor codebase. The only way to plug the leak is to rewrite that part of the system. Often, the programming team is unable to recognize that this code is a lost cause, particularly if they participated in its development. More commonly, the programmers know that this code is the problem, but they can’t talk management into the schedule slip that is necessary to fix it. In the end, the project takes longer to complete than if we had stopped and rewritten the offending code.

Unfortunately, a leak in software is rarely as visible or as easy to appreciate as a gaping hole in a hull. However, the programmers’ work to patch the system instead of fixing it is just as futile as the sailors who just keep bailing. And the result is nearly as predictable.

Poor Process

Another way this phenomenon is manifested is in adherence to bad processes. I worked on a project that used very poor configuration management techniques. The approach to version control was sloppy, and there were no controls for how integration servers were configured or how code was deployed for testing. Consequently, even though we would get successful tests on the integration server, we continually faced problems in production. These problems stemmed from several causes. Sometimes it was because of files that were edited on the integration server and not checked into source control, so they never got deployed to production. Or someone would set up the directory structure differently so that it would work on one machine but not the other.

When these problems appeared, the proffered solution was that people should be more careful. This case might be slightly different. Instead of thinking that you’re too busy bailing to plug the leak; in this case you believe that bailing may be all that’s needed.

I’m a firm believer that your test machines should mirror your production environment in every way possible and that you should deploy your code for testing exactly as it will be deployed to the production environment. And if I ever catch someone editing a file on a test or integration server, I’ll keel haul them!

No Time for Personal Development

I also see the “too busy bailing” mentality at work in peoples’ careers. As a hiring manager, I have interviewed hundreds of candidates for jobs over the years. I’m frequently amazed to learn how little people invest in their careers and the knowledge necessary to advance.

For example, most of my work has been on Object-Oriented projects. So, I typically ask OO questions of the candidates. One question is about how they learned OO programming. What books did they read? How did they hone this knowledge? Typically, I find that most candidates learned OO in college and have done nothing to build on that knowledge, other than their normal work experience.

I’ve also interviewed candidates for web development. So, I’ll get a resume from a bright young college student who is about to graduate. They tell me they want to be a web developer.

“Great!” I say. “So, have you ever built a website?”

“No.”

“Do you know HTML and JavaScript?”

“We had that in a class once.”

“Well, then what have you done to become a web developer?”

“I’m real busy with class right now.”

So, basically, this guy is looking for someone to pay him to become a web developer. I’ll always consider a new grad without formal experience, but I want someone who has done more than just sit through classes on their way to a degree. Show me some passion or interest in your area by working on something outside of class. Or at least have knowledge in the basic tools.

Tool Selection

The final way I see people being too busy bailing is through adherence to less effective tools. I often interact with people who have been using vi their whole career, or some other minimal editor, and just can’t be bothered to change. No amount of telling them how you can save them time will convince them to switch. They may even admit that they know they could be more productive if they switched, but they don’t want to take the time to learn a new tool.

Truthfully, this could be a case of the tool becoming the job rather than being too busy bailing. In that situation, a person spends so much time, say, hammering that they lose sight of why they are hammering: to build houses. So when a new way of driving nails comes along, they stick to their current way of working. “I’ve been hammering for 20 years. I’m not about to switch.”

Switching tools will always involve an investment in time. But if you pick the right tool, that investment will pay off rapidly.

So watch for signs of bailing in your own work and career. Consider whether there is a leak that needs to be plugged first. If not, then bail for all your worth. If you have spotted a leak and no one will listen, maybe you need to do a different kind of bailing.

Ideally, this is done logically and methodically, making sure to choose the technologies that best meet the stated needs and provide for a future growth path. Like most human activities though, this process is often subverted by the foibles of those involved.

Here are a number of Design Fail Patterns, ways that bad designs get chosen.

“To A Man with a Hammer, Everything Looks Like a Nail.” – Mark Twain

Sometimes a team makes an ill choice because of their background. There are more technologies available than ever before (see Software’s Cambrian Explosion). It is impossible to stay on top of every language, framework, and system. You do have to make a choice from the set of technologies you are familiar with or ones you know to explore.

Sometimes the right choice is the tool you have expertise with, even if another is more capable. Predictability is a key factor in the success of a project. Many projects don’t afford the time necessary to learn and master a new technology. So, success depends on doing the best with the tools at hand.

However, I have seen familiarity promote technologies way past their utility. I worked on a real-time communications system a few years ago. The architect on this project was a former Database Administrator. While he was a first-rate DBA, he knew little of object-oriented design or the design of large, complex systems. His design reflected his knowledge. Consequently, the system was designed as a transactional database with a thin veneer of objects to interact with the user and other systems.

I’ve also seen this work the other way. On another project we were building a system to manage patient records. While this was obviously a database project, the team treated this primarily as an object-oriented system, using the database merely to serialize their objects. All permissions, synchronization, and look-up took place in the object layer. To do that, they loaded all of the objects into memory when the system started up, with predictably poor results.

Every system we build has an essence that defines the nature and purpose of the system. For each, there are always technologies that are better or worse suited to that essence. It is very important to look past your familiarity and find the ones that best meet that need.

Design by Resume

Sometimes a team makes a bad choice because of a technology they want to work with. For a technical field, software development is full of fads and fashions. At any moment in time there is some hot, new technology that is supposed to render all others obsolete, and developers clamor to gain experience in these systems.

One such technology was Enterprise Java Beans (EJBs). A few years ago, the media was abuzz with articles extolling the virtues of this almost magical technology. I can hear the voice of Billy Mays now, “Try EJBs, the distributed data solution that removes stains and whitens your teeth.”

For several years, every Java project I worked on desperately tried to find a way to use EJBs. Developers who had never actually used EJBs fell all over each other trying to wedge them into the design. Ultimately, none of the systems I worked on found a good use for them.

Sometimes that hot, new technology will be the right fit. Just be sure you are picking it because it is the right tool and not because you want that experience on your resume.

Design by Magazine Article

There is an entire ecosystem in software engineering that exists just to tell you how glorious new technologies are. That used to be the domain of trade magazines—you know the ones, the large newspaper looking things that are always lying around the break room. Now, websites have taken over as the number one source of telling you what you should be using. Seminars and conferences are another source for this.

Regardless of the source, Design by Magazine Article occurs when the technology direction is chosen because of one of these experts telling you how to do things. This differs from Design by Resume principally in motivation. Design by Resume comes from the desire of the developers to expand their experience. Design by Magazine Article occurs when engineers put too much faith in the so-called experts. Often this occurs in management circles, like when a CTO has time to kill on a long flight in first class.

And this leads us to our final Design Failure Pattern…

Design by Management Fiat

This may be the worst of them all, and certainly is one of the most common. In this situation, upper management decides what tools and technologies will be used. Often this comes as an effort to standardize on a tool set, like when a company decides it’s a Microsoft shop or Java shop. Sometimes it is driven by cost, like when companies standardize on tools like Eclipse.

This pattern is wrong on many levels. First it robs the team of their sense of buy-in. This is an essential element in a team that is functioning at its highest level. Second, no tool or technology is right for every situation. I’ve used both SQL Server and Oracle. In many cases either will do just fine. In some cases, SQL Server is a clear win for its simplicity and lower cost. But sometimes you need the capabilities that only Oracle can give you.

Finally, this pattern is bad because the policy is written in stone. No matter how effective some other solution might be, once management has made up their minds they will not be swayed, at least not until the next hot-shot CTO comes in and talks them into the latest set of must-have technologies.

Friends, let me share with you the one sure thing I’ve learned about technology: it is hard. You are faced with innumerable decisions about which way to go. While there are no roads to guaranteed success, there are many roads to guaranteed failure. You need to keep your options open and make the best choices you can.

You might say that each was well adapted to a particular niche in the programming ecosphere. COBOL was a business language used on mainframes to write banking applications. FORTRAN was the language used by scientists and engineers. C was the choice for writing system code and operating systems. And so on…

Likewise, there were relatively few choices for libraries and frameworks. If you wanted a graphical front-end, you could use X Windows. There were a couple of Database Management Systems available, but usually one that was dominant on your platform.

Since then, there has been an explosion of new languages, technologies, and frameworks. In my mind, this is similar to the Cambrian explosion, a rapid proliferation of life forms that occurred around 530 million years ago. During this period, Earth went from having a relatively few and fairly similar life forms to a vast number of highly diverse life forms.

One explanation for this proliferation is the Snowball Earth hypothesis. According to this theory, there was a period where the entire Earth was covered by a sheet of ice. This created a uniform set of conditions for life. There was little need or opportunity for life forms to adapt to different conditions. So, there were relatively few life forms.

Similarly, the early years of computing saw a fairly uniform ecosystem for programs. Code was written to run on mainframes and later on mini-computers and personal computers. Still, the programs were very similar in that they were largely compiled programs and ran locally. Programs used text to interact with users.

The ice sheet was finally melted, it is believed, by the build-up of greenhouse gases over millions of years. Suddenly there are new conditions for life. New life forms come into being to exploit these conditions, producing the Cambrian explosion.

Similarly, the World Wide Web likely launched software’s version of the Cambrian explosion. The web has added many new challenges and radically altered the way programs are conceived and delivered. There was a great proliferation of languages and technologies to exploit these new conditions.

Though earlier developments like the personal computer and Graphical User Interfaces spawned a degree of new technologies, they cannot compare to the web for sheer number of new mechanisms. Within the Java ecosphere, alone, you can choose from Swing, Spring, JSP, Struts, JFaces, and more to build your interface, most of which were created to help deliver web content.

The Open Source movement is another evolutionary accelerator. There was a time when languages and frameworks were produced by a few individuals working at places like Bell Labs. With open source, communities are collaborating together to produce new technologies. This has greatly increased the rate of change.

I wonder what a Survey of Programming class is like now. It’s hard to imagine how you could cover the major technologies in a semester. Heck, by the end of the semester whole new technologies will likely have come into being. It’s exciting!

At this point, we’re pretty far along in the evolution of version control development. However, there’s a fundamental problem with all of these version control systems.  Even though they set out to do the pretty much the same thing, there’s no common interface to any of them.  Even worse, the interpretation of common concepts are completely different.  It’s not noticeable if you’ve only used one.  The more you use, though, the more obvious it becomes.  The only attempt at such a thing that I can recall is Microsoft’s SCC interface.  Unfortunately, it served a very specific purpose and aimed for the lowest common denominator.

If you have ever tried to switch from one version control system to another, you have suffered through this.  If you’ve ever had to port the version history from one system to another, then you likely gave up and stuck with the old system or lost all of your history.  The interoperability of version control systems is horrendous.

Standardized interpretation

Let’s start with version numbers, the ID that identifies a particular version of a file… how basic is that?  CVS has it’s own dot notation.  SVN and Team Server keep a global number that gets incremented when any file is checked in.  This difference in interpretation leads to fundamental differences in how these systems implement labeling and branching.

How could these common concepts be interpreted so differently? It means that in order to move from one version control system to another, you not only have to learn the new commands, but you must understand that system’s interpretation of what they mean.  Labeling and branching in CVS and SVN are very different, even though the basic concept is the same.  It would be nice to see some a standardization of the implementation of these concepts between version control systems.

Standardized commands

Imagine a world where databases each had their own proprietary language that was completely unrecognized by any other database.  Alright, maybe that’s not so far off from reality, but beyond PL/SQL, T-Sql and others, there’s ANSI SQL, which is the common language of all relational databases.  It theoretically (note the italics) allowed developers or DBAs to write SQL that could be understood by any database that supported ANSI SQL.  It’s the idea of polymorphism at work outside the code, creating a common interface to the functionality, yet allowing each database engine implement that functionality as they wanted.

Version control would be such a happier place if there was a common command language for it, that each version control system was required to implement. On a ground floor level, it would make the simple day-to-day operations consistent.  Update, commit, compare and revert would all be standard.  Once you learned how to use one version control system, you knew how to use ten version control systems.  Is this so hard?

Import/export standardized formats

A huge point of pain in version control is having to switch from one system to another.  It sounds crazy… who would switch version control systems at the same company?  However, it’s happened to me three times in my career.  Companies and departments merge, where both sides used different version control systems.  Sometimes your needs require a version control system with more functionality.  There are lots of reasons for switching systems.

Unfortunately, each time I’ve had to switch version control systems, it’s resulted in a complete loss of history. Therefore, there needs to be a standardized import/export format.  Many applications make use of XML as a way to import and export their data to share with other applications.  RSS is probably one of the best examples of this.  Version XML would allow you to export your version history for all files in the repository.  That history, as well as the files or deltas, could then be archived in tar or zip format into a single file.  The corresponding import functionality would be able to read this standard format and structure, and would be able to import that version history. This would completely remove the pain of having to switch from one version control system to another.

Version Query Language

Basic file check in and check out is the core of any version control system.  However, aside from being able to diff two specific versions of a file there is very little cross version analysis in most systems, despite the fact that the source control repository inherently contains this information. Going back to the SQL analogy used before, a version control repository is a database and users should be able to query it.

I would love to see a standard version query language and table structure that allowed you to run any query you wanted through the version control system’s engine.  You might be able to write queries like the following (pseudo-queries only):

Who wrote the code at a specific location in a source code file?
select author where file = “x” and line = y
where x is the file and y is the file line number.

Across all files, which version’s check in comments contain a specific string pattern?
select revision_number, file where comment like “x”
where x is the check in comment to look for.

What check ins has a particular person made in the last 10 days?
select file, revision_number where author = “x” and checkin_date >= y
where x is the user and y is the date 10 days ago.

Which check ins had the biggest effect on a particular file?
select top 5 revision_number where file = “x” order by lines_changed desc
where x is the file.

We took a stab at that in our Tools for Visual Studio product with the Find Version feature.  It allows you to find the versions of one or more files that match specific criteria, such as the ones above.  It does so with a GUI interface, not a query language like I proposed, though.  The most difficult part about this feature was finding a way to do this across several different version control systems, yet maintaining a consistent interface.

In an industry like software development, where most people understand the concept of one interface and many implementations, it’s amazing to me that this hasn’t caught on yet in the area of version control.  Maybe some day that will happen, and moving to a new version control system won’t waste time that could otherwise be used writing code.

Visual Basic 1.0

Sitting in between Turbo Tax ‘99 and Mavis Beacon’s Typing Tutor was this gem….  Visual Basic 1.0.  I almost couldn’t believe my eyes.  To me, this was on par with finding the missing link.  As a programmer, this was archeological gold, and it was on sale for fifty cents.  My kids saw the excitement on my face and must have thought that I’d found an XBox 360.  For them, Visual Basic was a major let down.

A lot of people think that VB is soft and if you program in it, you’re automatically a drooling hack developer who couldn’t program their alarm clock.  I cut my teeth on VB 4.0 in my first job, and learned that when combined with COM in C++, VB was a fantastic language for the job of making a user interface. That being said, VB still has some special memories for me.

The contents of the box were practically undisturbed.  The disks were all still in their original plastic wrap and the manual didn’t seem to have ever been opened.  Immediately, there are certain clues that tell you just how old it is (even though the box is copyrighted 1991).  First, the box contains two forms of media; 3.5″ and 5.25″ floppies.  To actually take a 5.25″ floppy out of its sleeve and hold it brought me back to the days of floppy doors and the red LED that told you the disk was being read.  The system requirements for VB 1.0 were Windows 3.0, a 286 processor and 1MB of memory.  Somewhat of a far cry from the Visual Basic of today.

I also loved the included “Companion Products and Services Directory”.  The third party marketing rush had already begun back then.  Most of the components in the catalog, though, are for connecting to a VAX server or to a dBase or Btrieve database.  There are a handful of charting components and widgets such as tree controls (not yet standard in 1991) and grids.  The reminiscing continues.

This box goes right up on my bookshelf at home next to the most revered books in my collection. Say what you will about Visual Basic, but it may be one of the most important developments in programming over the last 20 years for the simple reason that it allowed any non-programmer to write a Windows program.  If you think that’s not a valid reason for such importance, let me repeat… it allowed any non-programmer to write a Windows program.  It was Prometheus, stealing fire from Zeus and giving it to mere mortals for their use.

You no longer had to know C, and wade through Petzold, to write “Hello World” in a window.  Employees from any company with core business knowledge, but no degree in programming, could now quickly write customized applications.  Of course, the debate of whether this was a good thing for programming or not still goes on today.  However, regardless of which side you’re on, you can’t deny that VB was a major victory for bringing the PC to the business market.  Without VB, we may not even have a Microsoft today.

So thank you very much, guy from two streets down, who decided that Visual Basic 1.0 wasn’t important enough to keep, but too important to just throw away.  One man’s junk is another man’s gold, and I really struck it rich that weekend.

Read The Friendly Manual… or not

Many software products have changed over the years to cater to end users who don’t want to spend a lot of time learning how to use new software.  I first saw this in the game industry, where people can’t seem to be bothered to read a manual at all.  These days, games don’t even come with instructions.  They provide a tutorial level or integrated help that watches what you do and introduces you to the things you need to know as you play.  It’s brilliant, really.  The users don’t have to read a thing before playing, and who’d want to?  When I get a new game, I don’t want to waste time reading when I could be already up to level 10.  The game companies win too, because they don’t have to pay for the printed materials.  Everyone’s happy.

But how does this translate outside the game industry?  It’s been tried before, with much less success.  Clippy was the spokesman for the first wave of learn-as-you-go user experiences.  We all know how that turned out.  “One of the worst software design blunders in the annals of computing,” wrote Smithsonian Magazine.

So users didn’t like being told how to use the software while they used it.  Another form of learning that is not always well received is the tip of the day.  I know my first order of business after installing new software is checking the “Never, never, ever show me this again” checkbox on the tip of the day dialog.

Wizards also tried to ease the user into getting up and going without having to wade through options pages and understanding all of the menus and toolbars.  Although wizards have had some success, it’s still a paradigm that’s seems old.  When I think of wizards, I feel like I’m flashing back on an episode of “I Love the 90s“.

At the very least , there hasn’t been a lack of effort to try to help users figure out how to use their software without the manual.  Yet, most of these attempts seem to fail.  It’s as if users don’t want to read how to use the software and can’t be bothered being shown how to use it by the software itself.  Part of me wants to rant about how idiotic that is and the other half of me recognizes that I fall into that group.

Done programming?  Great, now get back to work.

I’ve spent most of my programming career writing programs for in-house use, or writing programs that were bought by large companies to be rolled out in-house.  The thing that all of my work had in common was that the end users were not end users by choice.  The software I helped write was all rolled out in some fashion to a large group of people whose jobs depended on them learning the software.

Here at SlickEdit, I’m no longer writing software that users must adapt to.  Instead, I’m writing software that users  make a conscious choice to use or not use.  The choice to use it hinges heavily on the trial, and if the user can’t get the trial installed and doing spectacular feats in less than five minutes, then the opportunity is completely lost. The bottom line is that the most important software performance metric is not how fast my code works, but how fast the user can use it meaningfully.  If that doesn’t happen, then the user loses interest and all of the great work we’ve done will never be seen.

That’s quite a psychological transition for me, because I’ve never focused before on instant user gratification.  One of our strategies involves the software helping users through an optional tool window, called the Tools Assistant,  which is part of the “Tools for Visual Studio” product.  It stays off to the side or can be closed if the user doesn’t want the help.  But there’s also a lot more to this effort than just adding up-front convenience to the software.  We also have to think up new ways to get users to see the product in action with very little effort on their part, often without even downloading it and installing it.  This involves a lot of non-programming work, like video script writing, screen shots, articles, etc…  It’s certainly an interesting change of pace, but it really pushes the limits outside of my programming turf.  I took a break the other day to fix bugs and it was refreshing just to see code for a while.

I love a change of pace… it keeps things interesting.   However, trying to figure out how to pitch a software product may be one of the biggest challenges I’ve had as part of a software development team.  I certainly never took any marketing classes in college, and at this point they’d all be irrelevant anyway.  So I’m no longer focused on reducing the time it takes to perform complex operations… my focus now is on reducing the amount of time it takes a new user to say, “wow, that is so cool!”  So far I can’t find any way to calculate the big O for that, but I’m trying.

Unfortunately I discovered this technique after we finished the documentation and shipped the plug-in, but hopefully me pointing it out here may help some users. 

Also, don’t forget the “Activate Editor” command in Eclipse (F12 by default).  If you are using _eclipse_execute_command to jump into different Eclipse Views and search around mouse-less, hitting F12 will jump you back into the last active editor.

<update> 

Check out this thread of the SlickEdit Forums for adding a generic Eclipse Pass-through Command: http://community.slickedit.com/index.php?topic=3549.0

From the post:
If you are evaluating 3.4.0 for your company, you can make this happen easily.  One of the best features in Core 3.4.0 is the introduction of _eclipse_execute_command, which is discussed in the user guide/readme, and also a little more in my post here: http://community.slickedit.com/index.php?topic=3816.0 .  This is the idea that Rob suggests in this thread.

I’ll take this opportunity to give a brief tutorial on how to integrate that “Activate Task” shortcut into the SlickEdit environment.

First you need to know the command id of what you are trying to execute.  I used the method described http://evans-stuff.blogspot.com/2007/10/it-seems-that-im-not-only-one-still.html , in which you create a Simple Cheat Sheet and use the Command Browse button (see first screenshot).

Then I just used the search field to find the command (see second screenshot).

Now that I had the command/parameter info, I opened up the Slick-C macro file where I write my custom commands (ryan.e), and added functions for Activate Task and Deactivate Task using _eclipse_execute_command (see third screenshot).  Remember to load your macro file with F12 after writing the functions.

Then I used the SlickEdit Keybindings dialog to bind eclipse_activate_task to Ctrl + F9 (see fourth screenshot), and voila.  Hitting Ctrl + F9 in a SlickEdit editor will launch the Mylyn Activate Task dialog.

It may seem like a lot of steps, but it’s really not.  This whole process took me less than 10 minutes including the time I took to capture/crop/annotate the screenshots.  You can use this method to execute almost any Eclipse command from any plug-in from the SlickEdit environment.

- Ryan

I like the generic term, “change request” for all changes in a system. But it’s very important to know whether it is a defect or a feature request. In my lexicon, a “defect” is something that doesn’t work as spec’ed; a feature request is a request to alter the intended behavior. Overall, I prefer the word “defect” to “bug”. “Bug” sounds kind of cute. “Defect” is a harsh, painful word, which is exactly what I want associated with any part of the product that doesn’t work properly.

Depending on who you are talking to, they either don’t care about this distinction or they care greatly.

Customers generally don’t really care which it is. They just want the behavior changed. To them, it is a defect as in “defective”, and they don’t care whether it was spec’ed wrong or implemented wrong—it’s just wrong and they want it changed. Am I any different about the products I use?

As a product manager, I care greatly about this distinction because they tend to address different groups. Defects are typically the chief cause for dissatisfaction with a given product. Generally, customers wouldn’t have bought the product if it didn’t have the features they wanted, but key defects are sometimes discovered only after you’ve purchased. Certainly, if you have many obvious defects they will prevent new customers from favorably evaluating your product. Further, defects in a program add to the burden of development, slowing work on related capabilities.

Feature requests add new capabilities to the system. Though these are beneficial to existing users, they primarily want the existing set of capabilities to work as well as possible. New features are a means to broaden the product’s appeal. They can also provide incentives for customers to upgrade or participate in maintenance programs that include free updates.

Developers are also passionate about this distinction, but for a different reason. For them, the concern seems to be that a defect is considered a personal affront to their ability. I’ve spent more time arguing with some developers whether a change request was a defect or a feature request than it would actually take them to fix the problem (though, not at SlickEdit, of course!)

Balancing priorities for defects versus feature requests is one of the most challenging tasks a product manager faces. There are different voices pulling you in different directions: sales, marketing, customers, and developers. All have different things they want to accomplish in the next release.

At SlickEdit, we try to strike a balance that gives as much as we can to each group. Each major release contains new features that we think can improve how you write code. We also try to knock out as many defects as we possibly can.

Using Code Annotations to Write Review Comments
The Code Annotations feature in the Editing Toolbox is extremely useful for writing code review comments because it lets you attach comments to specific locations in the code without altering the code itself. You can bring up the Code Annotations tool window by clicking SlickEdit > Show Code Annotations.

[Click for full size image]

The first step when writing code review comments is to create an annotation file to store all of your code review comments. You can then send this file to the code review organizer when you’re done. You can use the Annotation File Manager to create a file called “Code Review – Bob” (or whatever your name may be).

Writing Comments About the Code
After applying the “Scott’s code” visualization scheme that we made in the first article, we can navigate through the sections of code that Scott has written. On line 497 of PackageBaseWhidbey.cs, we see that he’s doing a GUID comparison using a literal string. This goes against coding standards, so we’ll log a comment that the string literal needs to be defined as a constant. Put the cursor on that line and click the New Annotation button on the Code Annotations toolbar. This will bring up the New Annotation dialog.

We’ll create a review comment, which is one of the standard annotation types. We’ll also select the “Global : Code Review – Bob” scope, or category, which will put the annotation into the code review file we created earlier. After filling out the fields and clicking OK, a purple highlighted marker is placed on the line of the new comment.

[Click for full size image]

Once you create an annotation, it gets an entry in the annotation list. You can select that entry to see a summary of the annotation, or you can double click on it to jump directly to the code it is assigned to. This makes it easy to get to the code that you’ve commented on.

We also found a bug on line 431 of FileUtility.cs, so a bug annotation can be logged for that. This new annotation has a red highlight to indicate that it’s a bug type.

[Click for full size image]

It’s helpful to only show annotations that you have created for the code review, without the clutter of others in the list. You can filter out all non-code review annotations by using the Annotation Filter Configuration dialog, available on the code annotations toolbar. Select Filter by Scope and select the “Global : Code Review – Bob” item. Now, only your code review annotations will be visible in the list.

Wrapping Up Your Review
Once all of your code review comments have been completed, they will all be contained in the file “Code Review – Bob.sca“, which we created at the beginning of the article (code annotation files have an extension of .sca by default). That file can then be sent to the code review organizer.

All of the received code annotation files can then be imported by the organizer during the code review meeting, where they can be discussed. Reviewing code this way maintains a tight link between the code review comments and the actual source code, and is far better than trying to manage the process with pen and paper, or a set of text documents.

You can also create a report of the annotations to print before the meeting, or to send to other developers. To do this, click the View annotation Detail toolbar button. The Code Annotation Details dialog will be shown and each annotation in the list will be shown in the report. A small red document icon will appear by each annotation that may be clicked to navigate to that annotation in the source code. The report can be exported to HTML or printed.

[Click for full size image]

The next step will be the actual code review meeting, which will be the focus of part 3 of this series. Once the code annotation files are pulled together from all of the reviewers, those comments can be discussed and updated. After the code review meeting, they can be exported to a single code annotation file and emailed back to the group. The developer being reviewed then has a clear set of action items as a result of the meeting.

Just like a novelist must have a solid foundation of grammar and vocabulary, a good programmer must understand the fundamental APIs for their language. But a novelist cannot write a novel with grammar and vocabulary alone. It takes creativity to turn the words into a meaningful connection with the reader. The equivalent of this in programming is usability for the end user.

Usability is such a bad word. Dictionary.com defines it as “capable of being used”. Thanks for that. However, scrolling down further, it also references the following as it relates to programming:

The effectiveness, efficiency, and satisfaction with which users can achieve tasks in a particular environment of a product. High usability means a system is: easy to learn and remember; efficient, visually pleasing and fun to use; and quick to recover from errors. [1]

Now we’re getting somewhere! This is a perfect analogy to the novelist trying to connect to the reader. Investigating further, I found the HCI (Human Computer Interface) page at Wikipedia. I was expecting to find the softer side of programming, sort of a feel good, warm milk and teddy bears approach to software. However, I pretty quickly realized that it’s a whole other science in itself.

After creating what I think are some really compelling features in our Tools product, I’m having to look back on it now and figure out how to optimize it for the user. That’s so hard to do when you’ve worked with a thing for so long, or even worse if you’ve created the interface to it. Just like I wrote in my “Zen Mind, Programmer’s Mind” post, I really need to go back and approach it as it I knew nothing about it. I’ve always approached HCI by imagining the way that I would want to use it. It’s so easy to forget that I’m just one person and there will be so many more people out there using my software that won’t agree with the way I use it.

HCI is fairly new to me, but I’m always interested in learning something new. The problem to me is how amorphous it is. There are principals, guiding rules, methodologies, and such, but there are no concrete steps. I guess that’s how it is though when you get into the areas of programming that make the leap from straightforward answers to creative problem solving.

I wonder if someday in a hundred years or so we’ll talk about software like we talk about classic literature now. Maybe someday there will be a Shakespeare or a Mark Twain of software. Maybe someday you’ll be able to see a piece of software and say that it’s a distinctive program for a particular developer group. The closest thing we have to that right now is Apple. Someday I hope I can look at may own software and think, “Yeah, that was my style.”

1. The Free On-line Dictionary of Computing, © 1993-2007 Denis Howe

• First, Last
• Next, Previous
• Begin, End
• Push, Pop
• Draw, Erase
• Add, Remove
• High, Low
• Yes, No
• Stop, Go
• OK, Cancel
• And, Or
• Up, Down
• Left, Right
• True, False
• In, Out
• Plus, Minus
• Fixed, Floating
• Open, Close

Each pair is opposite in meaning and different in length. When I study these pairs of words, I can’t help but be absolutely convinced that the inventors of the English language gave absolutely no consideration to the fact that (thousands of years later) there will be millions of programmers writing code in mono-spaced fonts and really, really wanting it to line up nicely, but thwarted by this lack of similarity in length.

If you are smart, you’ll stop reading now, the rest is a bit predictable and boring. The point of this article is that it is annoying to write code that looks like this.

So much is it annoying, that the monosyllabic, four letter abbreviation “Prev” has nearly became a universally accepted substitute for “Previous”, within the confines of software, at least.

You are still reading? Ok, fine. Really, if you have been programming at all, you have already encountered this, and you know everything I’m going to say. You could have stopped at the title, in fact.

There are a few exceptions to this rule of opposites — Get, Set, North, South, East, West, Insert, Delete, Internal, External, Throw, Catch. Get and Set are so loved, I think for their matching size and rhyme, that we have invented new words for those types of functions (getters and setters). Of course, “setter” isn’t a new word, but prior to the explosive discovery that both get and set had three letters, a “setter” usually referred to a breed of canine. What is really impressive are the applications you might find map directions applied to. Not in SlickEdit, but elsewhere, I have seen North and South used for cursor movement where you would have logically used Up and Down. Likewise, East and West have been applied to where you might logically think Left and Right and even, Next and Previous. My theory is that to some, alignment is a worthy cause, so much so that you may chose a naming scheme which involves a level of indirection.

Certain shell languages have employed mirror spellings of keywords as a level of indirection between opposites and like-sized keywords. Thus you find do, od, if, fi, case, esac. The first time you see it, you will think, “What is an esac? If it’s anything like an email, I do not want to touch it.” But, it may grow on you, as the Bourne shell has grown on Unix.

Acronyms were all the rage in the old days when it really did matter that your code be small and fit on a punch card. Some continue to survive and are frequently used, such as Gt for greater, Lt for less than, Eq for Equal, Ne for inequality, Hi for high, Lo for low, T for true, F for false. Sometimes you see hybrid abbreviation pairings, such as Up, Dn, or Add, Del.

Some programming language designers have addressed this issue with more symbols. APL is well known for it’s elaborate character set, “⌊” for floor and “⌈” for ceiling, for example. C++ introduced operator overloading and programmers followed that path of slow, destructive insanity towards standardizing — and ++ as next and previous iterator methods, among others.

But, in the end, this problem of opposites being different is not a programming language issue, it is a natural language issue. It’s a problem with the English vocabulary. And there is little we can do about that. Until we find a natural language invented by linguists who really thought about writing code in monospace fonts, our code will never be aligned as well as it could be.

I can’t say that I’ve met too many developers that eagerly looked forward to reviewing code. Most developers understand the importance of code reviews, but many have experienced the pain of poorly run code reviews. Although SlickEdit Tools does not have a “code review” feature, it provides several features that can be used together to make a code review run smoothly. A well done code review process can be the difference between developer loathing and developer buy-in.

Because code reviews are such a big topic, this article will focus on some of the steps that lead up to a code review. Code reviews typically focus on the work of a single developer, so we’ll start there. We are going to be code reviewing the developer with ID SLICKEDIT\shackett (or Scott) in source control, and we’ll be reviewing his work since March 3, 2008, which is the date of our last (fictional) release.

Finding the Best Files to Review
Our first challenge involves finding the set of files that Scott has worked on since March 3, 2008. We’ll use the Find Version feature of the SlickEdit Tools Versioning Toolbox as our starting point.

Find Version allows you to query versions of the source code files in your solution. The code review organizer can use this feature to find an ideal set of files to review. Simply click SlickEdit > Find Version to bring up the Find Version tool window. For this example, we’ll find versions with the following criteria:

• Since date: Finds all versions checked in since a particular date, such as the last release.
• Developer name: Finds all versions checked in by one or more specific developers.

These two criteria are used to find all versions checked in by Scott during the latest development cycle (March 3, 2008 – present).

No development team has the resources to code review every file in that list, so it’s important to find the best candidate files to review. Therefore, the next task is to look through the results and find a sampling of files that represent the most important or complex code. You might also include some files that have a high number of check-ins by that developer, which indicates high rate of change, or churn. These are the ideal candidate files to be reviewed. Email the names of those files to all developers who will be participating in the code review.

[Click here for the full size image]

In this example, PackageBaseWhidbey.cs has had several changes and is a very important file, so we’ll include that in our code review process.

Loading the Files to Review
When a developer is ready to prepare their review comments, they should close all other files and open the files in the list sent by the code review organizer. This can be done quickly using the Load Files feature in the Editing Toolbox, which allows you to quickly filter the list of files in your solution and open the ones you’re looking for. Click SlickEdit > Load Files to use this feature.

By typing “basew” in the filter, we narrow down the files in the list to only those that include that text in their file name. We’ll select PackageBaseWhidbey.cs and open it.

Isolating a Developer’s Work
One of the most difficult things to do when reviewing the code of another developer is actually identifying the work that that developer did, especially if it was done as part of a team. Once you have PackageBaseWhidbey.cs open, we’ll use the Version Visualizer feature of the Versioning Toolbox to see which parts Scott has worked on. Click SlickEdit > Version Visualizer to show this tool window. Next, select “Default User Scheme” in the drop down at the top of that tool window.

The versions of the file will be processed and the tool window will list the names of all developers who have contributed to the current state of the file. The editor also becomes colorized into segments of lines that identify who wrote each line of the file.

[Click here for the full size image]

You can find Scott’s name (SLICKEDIT\shackett) in the tool window list and double click on it to go to the first line of code he contributed. You can then use the next and previous button on the tool window to navigate through the blocks of his work.

To make Scott’s work stand out more distinctly, select his name (SLICKEDIT\shackett) in the list and click the “Toggle Selection Visibility” toolbar button. When toggled on, Scott’s work will stand out, and all other developer’s work will be dimmed out. This allows you to quickly see what code is Scott’s and what code isn’t. You can click this button again to toggle it back off.

[Click here for the full size image]

Another option is to assign a unique color to Scott. To do this, click the Configure Visualization Schemes button on the Version Visualizer toolbar. This will bring up the Scheme Builder dialog. We’ll create a new scheme to highlight all areas of code worked on by Scott. Click the Add new scheme button and give the scheme a name of “Scott’s code”. We can now add a scheme item for Scott and give it a color of bright red.

[Click here for the full size image]

We can save this visualization scheme and then apply it by selecting it in the Version Visualizer drop down. This same scheme can be applied to any file to highlight areas of the code written by Scott.

[Click here for the full size image]

If you find a block of code written by the developer being reviewed that looks questionable, you may want more context about the developer’s intent, such as the check in comment made when that section of code was checked in. This information is very important for creating meaningful code review comments. The easiest way to do this is to see which version that code was checked in as, and look at the comment associated with that version. To do this, select “Default Relative Age Scheme” in the drop down at the top of the Version Visualizer tool window.

[Click here for the full size image]

Again, the versions of the file will be processed, but now the tool window will list the IDs of all versions that have contributed to the current state of the file. The editor also becomes colorized into segments of lines that identify which version last updated each line of the file. The colorizing of each segment corresponds to the age of the version it was checked in with (dark is oldest, light is most recent).

You can find the version associated with the questionable code and take a look at the comments associated with it. You can also use the next and previous button as before to see all of the code in the file that was updated as a result of that check in. For instance, we may have disagreed with the AddMenuCommandHandler function being public. We can see that change was part of version 762. By hovering over that version in the Version Visualizer tool window, we get a better understanding of why the function was made public. All of these features assist the team in making judgments about which code to review. They also provide some insight into the motivation the developer being reviewed might have had when checking a set of code in.

Next is the task of actually commenting on the code. This task is always best done in electronic format, in a way that can be pulled together as part of the code review meeting. The next article in the series will go through some of the features of SlickEdit Tools that facilitate writing comments about code and tying them directly to the source, without modifying the files.

A programmer’s bookshelf was more than a reference library though; it was your peer resume. Other programmers would look through your bookshelf the same way that animals size each other up in the wild. When you started a new job, your bookshelf contents were like the cologne and nice clothes you put on for a first date. It was a huge part of the first impression you made and helped define what you knew. Did anyone care if you’d really read those books? Of course not! Just seeing Design Patterns, Introduction to Algorithms and The C++ Programming Language was enough to grant you elite status your first day on the job (at least to those who mattered).

At my desk right now, I have approximately thirty books on the shelf. I’ve read them all from cover to cover, some of them several times. However, I haven’t read any of them in the past five years. At times, I’ll crack one open for a quick reference to something I can’t find quickly online, but seriously, they’re relics. I know that I should just do the smart thing and admit to them that the internet has caused their jobs to become redundant. I should tell them that the bookshelf is being downsized, and that they’re jobs have been outsourced to the web servers at Google. I just can’t bring myself to do that, though.

Every one of them has, in some strange way, come to mean more to me than just the information they contain. I can look at the cover of almost any book on my shelf and remember the reason I bought it, the project I was working on when I read it, and the difficult problems that it helped me work my way thorough. Many of the books have pictures of the authors on the cover, personifying them. All of the books make me reminisce to the period of time when they were read, the same way that so many songs from my first year of college do. I feel like I could take my programming books out for a beer and have a blast catching up on old times.

My programming bookshelf isn’t about learning anymore, and it’s certainly not about impressing anyone. I may at some point retire them, but not anytime soon. They sit on my shelf like old friends who I want to share my new programming experience with. They helped me out through tough times and I still want them to be there for all of my latest projects. I think my COM ATL books are grudgingly impressed with all the new-fangled .Net stuff, though I don’t think they trust it. My sockets books like to shake their walkers at web services. And of course, my first HTML book doesn’t think this fancy web 2.0 nonsense looks anywhere near as good as the first Geocities home page it helped me make.

“I don’t care if you suck at writing. I don’t care if nobody reads your blog. I don’t care if you have nothing interesting to say. If you can demonstrate a willingness to write, and a desire to keep continually improving your writing, you will eventually be successful.”

How this applies to us

We began blogging at SlickEdit a little over a year ago. Not written by a single person, the blog is a group effort authored by the dev and support teams. Our goal for the blog was to better connect with the developer community at large and to become an active participant in online discussions . The ‘Hello World’ blog gave us the perfect platform to share our thoughts, opinions, and expertise on a myriad of technical issues.

From software management and best practices to managing the first days on the job, the SlickEdit team has shared their thoughts, tips, real world experiences, and genuine joy of coding with the online community. I am very happy to say that the blog has been a huge success. With hundreds of thousands of visitors from over 176 countries and territories, the SlickEdit blog has outperformed our wildest expectations.

What has been really exciting are the hundreds of comments we have received on the blog, as well as link backs, that have really allowed us to connect and interact with the online community – the whole purpose of the blog to begin with. On the social media side, we have been Dugg, Reditted, StumbledUpon, Dzoned, DotNetKicked, Delicioused, Hacker Newsed, etc… more times than I can count. Exciting stuff and we can’t thank you enough.

Just in case you have missed any posts, here are a samples from each month since we began the blog.

Visit the blog archives for a complete list of all posts :

April 2007

Is Your Editor Working Hard Enough?

May 2007

Top Ten Reasons NOT to use SlickEdit

June 2007

Learning to Fly: The Musings of a New SlickEdit Employee

July 2007

Programming Language Wars

August 2007

SlickEdit 2007 For Windows Development

September 2007

Creating a PHP 5 Extension with Visual C++ 2005

October 2007

Comfort, Habits and Ruts in Software Development

November 2007

C# with SlickEdit : No Visual Studio Required

December 2007

Classical in a Digital Age

January 2008

My Programming New Year’s Resolution

February 2008

Plug-in Extensibility Through Reflection in .Net and Java

March 2008

Software Schedules and the Parable of the Loaf of Bread

April 2008

BASIC and the Rubik’s Cube

May 2008

Tutorial: Adding Language Support to SlickEdit

June 2008

“Management” is a Dirty Word

 All

Complete list of all posts for SlickEdit

I believe that all teams need management. That’s not to say that they all need a manager; some teams do manage themselves. Effective management gets the most out of a team by setting clear goals and minimizing time lost to indecision. A good manager bridges the gap between the business team and the technical team, making sure that both viewpoints are properly considered. A strong development manager can bring a process-centric view to the development team that seeks to improve daily workflows and operations.

So, what’s wrong with “management”?

I think the core reason that software management is so reviled is that it is so rarely done well. In my programming career, I can divide my previous managers into 3 categories:

1. Benevolent, useless, harmless—this is the category into which fall most of my previous managers. They did a reasonable job of passing along information and managing schedules, but I never really felt they were helping me get my job done. I spent a great deal more time giving them status reports than receiving guidance.
2. Malevolent, clueless, harmful—fortunately this category contains only a few of my previous managers. These are the ones who made the job much harder than it needed to be. Sometimes it was done to further their individual goals, like the manager who stuck us with an unreachable milestone so he could get a 30% bonus. Others, it was because they had no idea what we were doing and didn’t have the courage to admit it.
3. Effective, purposeful, supportive—by far the smallest population, this is the category we wish all managers fell into but so few actually do. These are the ones who truly help you get your work done by providing the kind of guidance and environment you need to succeed. Tom R., you were the best!

How did we get here?

There are so many contributory causes for this problem. The first group, above, is composed of good people who just don’t know what to do. The second group shouldn’t be in charge of themselves, let alone others. I can offer little help to the second group, so let’s focus on the first.

There are two kinds of development managers: those with a strong programming background and those without one (henceforth called “programmers” and “non-programmers”). Even if you have some programming experience, it may not be enough to qualify you as a programmer. You have to have done enough to be considered as a peer on your programming team. I divide managers into these groups because they face different challenges. I’ve worked for managers from both backgrounds and neither is a guarantee of success or failure. My best manager learned his craft managing supermarkets before he went into software development.

To be a successful development manager, you need to know how to manage and enough about software engineering to make appropriate choices. Oddly enough, both groups seem to struggle with the first item. Though the non-programmers tend to have better communication skills than the programmers (if they didn’t, what the heck were they hired for since they’re not programmers?), few of them in my career were skilled managers.

Unique Challenges

The unique challenge faced by the non-programmers is their lack of knowledge about software development. This often hinders their decision-making. A common sign of this is an insistence on keeping to the schedule when a minor slippage could make a huge difference later. When you’ve been around software development long enough, you learn that schedules are fluid. What you do today can make your work tomorrow easier, or harder, depending on the quality of the design and implementation. It takes experience and insight to know when to make these tradeoffs.

Another common problem for the non-programmer manager is not being able to call shenanigans when a developer is snowing you. Even as a programmer, you will never know someone’s code like they will, but you will know from your experience when a developer is likely doing something wrong. My background has helped me to sniff out cases of “design by resume”, where developers chose a particular approach in order to get a trendy new technology on their resume. A non-programmer manager would have a hard time asking the appropriate questions to recognize this.

The programmer managers also face unique challenges. The first is the temptation to code and manage at the same time. I read where others actually recommend this as the desired situation. In my experience, the two activities are incompatible. Effective coding is about immersion, getting into a state of flow, and being very productive. Effective management involves being available to your team to tackle their issues when they arise. Even when I wanted to try to keep coding, I’ve never had a position where the management responsibilities didn’t crowd out any time I allocated for coding. As a manager, my favorite means of being involved with the code is to participate in design discussions and code reviews. This keeps things at a high level and still allows you to contribute your knowledge and experience.

Another problem for the programmer manager is trying to be “one of the guys”. This is manifested as a manager who is hesitant or unable to provide negative feedback. Often, these kinds of managers are promoted from within the team, making this even more of an issue. These managers still view themselves or want to be considered to be a member of the development team rather than its leader.

As a manager, your primary allegiance must be with the business team. Your job is to take their goals and translate them into effective plans to accomplish them. Where you think these goals will lead to problems, you need to point that out. However, if you can’t get them to change the goals, then you need to sign up to them and do your best to accomplish them. Programmer managers sometimes have a difficult time making this change.

Shared Challenges

The most common shared challenge is a lack of knowledge about how to manage. Most of the managers I have worked for had no formal training in management. At best they had a seminar or two. Few ever read any books on management or software development management. Since they, too, have had few truly effective managers, they have no guidance on how to manage. They just don’t know what to do.

An example where this shows up is the weekly status meeting. Most managers have one. They have one because their previous managers had one. In its most typical form, the status meeting lasts for an hour or so while the manager has a conversation with each member of the team, discussing what they are doing. The theory is that having this as a team fosters teamwork and helps everyone to know what everyone else is doing. In reality, the rest of the team already knows or doesn’t care. So this ends up being a large waste of time as the manager has a one-on-one conversation with each team member in front of the rest of the team.

Don’t get me wrong, I’m not saying that status meetings are wrong. But you need to choose to have one because of the benefits the team will get from it, because it is right for this team. Instead, most choose to have one because that’s how they’ve been managed in the past, and it is a visible sign that they are in charge. One of the primary goals of management should be to achieve stated goals with as little interruption in the daily work as possible.

The Solution

What we need to solve this is the same thing we need for all leaders: wise, beneficent individuals with a commitment to goals and compassion for their team. In software development, you need to add in enough knowledge to be mindful of the unique challenges in our field. To erase the pointy-haired boss from our minds or at least remove him as the dominant figure in engineering management, we need enough developers crossing over to become committed managers or enough business managers to gain an appreciation for software development.

As programmers of an application or feature, we quickly develop our own preconceptions as to how the software should work. Every day that we spend working on something, the use patterns of that feature become more and more hard wired into our brain. The end result is often a piece of software that works the way that we would expect it to. However, once that software gets released into the wild, many people are going to be using it, all of whom have never seen or touched it before. As a rule of thumb, each of those people will approach it with different perspectives. Each person will use it in a different way, and have different expectations of what it should and shouldn’t do.

Requirements are always necessary, but it would be impossible to capture everything in the requirements that any user would want or need, especially when it comes to the more subtle areas like UI workflow. Important use cases can also go completely undetected until a real end user actually sits down to work with it. Because of that, it’s important to remember that even the best requirements are not guaranteed to be intuitive or even correct. To help with this, we’ll need to bring in a Zen Buddhist master.

Zen Buddhism in Application Development

There are a handful of books I’ve been fortunate enough to stumble across that have changed me in some way. Those books are the ones I keep going back to, to remind me of that moment when I’d learned something new, yet felt like I’d known it all my life. Zen Mind, Beginner’s Mind by Shunryu Suzuki is one of those books. In it, the author and Zen master teaches the importance of “beginners mind”, which is the concept of constantly seeing with new eyes. It’s a teaching that he recommends for all aspects of daily life, though I doubt he ever imagined software development would be on that list.

As developers, we need to see our work from two perspectives:

• Expert’s perspective: From this view, we make sure that the software is meeting the known requirements, which is our primary goal.
• Beginner’s perspective: From this view, we try to see the software as though we’ve never used it before and constantly ask the question, “Does that make sense?”

These may seem very similar, but they’re not. For instance, let’s create a signature in Microsoft Outlook.

Requirement: Allow the user to specify text to be automatically appended to every outgoing email. (Sounds simple enough…)

Implementation:

1. Click Tools > Options.
2. Click the “Mail Format” tab on the options dialog.
3. Click the “Signatures…” button on that tab pane. This brings up the “Create Signature” dialog.
4. Click the “New” button. This brings up the “Create New Signature” wizard dialog.
5. Enter a name for your signature and select that you want to start with a blank signature. Now click the “Next” button.
6. Type your signature. When you’re done, click “Finish”.
7. Click “OK” on the “Create Signature” dialog.
8. Your new signature is now added to a list of signatures on the “Mail Format” tab pane. Select it and click OK.

Do those steps fulfill the requirement to create a signature? Check. Would a new user to Outlook have any clue how to do that without digging through help? Fail. This is a clear case where the development team did not look at final product and ask themselves, “Did that make sense?” The obvious answer is no.

There was a fantastic blog post recently called “The Great Ubuntu-Girlfriend Experiment“. In this post, the author has his girlfriend use his latest installation of Ubuntu as a way of getting a beginner’s perspective on it. He winds up with some very interesting conclusions, specifically “that the geeky programmers and designers assume too much from the average user”.

End users are demanding more and more ease of use out of the box without having to go to help (much to the dismay of our tech writer). Think about the Geico caveman… buying insurance with Geico.com is so easy even he could do it. Ease of use and intuitiveness are so in demand that Geico launched a massive marketing campaign with that as its centerpiece. The commercials don’t say anything about price, customer service or any of the details of their policies. It’s just easy to use… and that pulls in huge numbers of people.

Putting It Into Practice

Having beginner’s perspective on your own software sounds much easier than it really is. Stepping back and using the software without preconceptions involves being honest with yourself. Sometimes it’s easier to give in to the fact that the software might meet the requirements, and that task can be considered done. However, it’s those little touches like usability that can bring an application to the next level, and move it up from good to best. Finding those usability issues can only be done by being objective about your own work. It’s far better to find those issues during development than when an end user first sits down to try the software.

Whether you use Zen mind, caveman mind or girlfriend mind [ducking behind my chair], try and take the time to step back and ask yourself if you would love your software just as much if you were trying to figure it out for the first time. Just like meditation, it’s a practice that gets easier every time you do it. Soon, it should become a normal part of your daily approach to software development. Of course I’d be lying if I said that I had actually attained this goal, but I try.

I have used the freely available book “The Great Logo Adventure!” as a reference in this article. Please note that I am not an experienced Logo programmer, so if you bear with me, you can learn how to add language support and I can learn something about Logo.

Step 1: Defining the language

Go to Tools > Options…, and navigate to Languages > “Language Manager”, then click on “Add Language…” Enter the following:

• Mode name: Logo
• Associated extensions: logo lgo
• Color coding: leave blank

Step 2: Color Coding

Now navigate to your Logo language settings and find the “Color coding” page.

Click on the top-most “New…” button to create a new Lexer and name it Logo. Now, we need to define the color coding. Let’s work left to right, starting with the Tokens tab.

Logo is case-insensitive, so uncheck “Case sensitive”. The identifier characters can be left pretty much as they are. Logo, in fact, will allow nearly anything to be an identifier, but in practical terms, the typical C language style identifiers are adequate.

Next, we add Keywords. The list below is fairly complete, though there is a fair amount of room for interpretation with respect to what is a keyword and what isn’t in Logo. Note that when you add new Keywords, you can add several at once if you separate them with spaces.

Now switch to Preprocessing and add:

And Punctuation:

And Operators:

Now switch to Library Symbols.

This is where you would typically add coloring for functions that are built into the language or included with the standard language libraries. Since Logo has nearly 500 built-ins, it would be senseless to try to type them all in manually. The attached hotfix includes a file, “logo_builtins.txt” which contains all the built-ins. This file was constructed by opening the help file for MSWLogo (Microsoft Windows Logo, by Softtronics, Inc.) using SlickEdit’s Help Indexer (”Help” > “Configure F1 Index Help”). I added the help file, then clicked on “Export…” to extract the index entries, then edited out the few things which were not library functions. In the Color Coding dialog, click on “Get…”, point it at this file, and it will pull in all the words in the list file.

Note that the color coding engine is not perfect is the keyword coloring. Logo is very context dependent whether a symbol is being used as keyword or just a word or list. Lists are sometimes code, sometimes strings. The color coding engine has no idea about these rules, so it sees a word that matches a keyword and it colors it. This is simultaneously quite useful, quite annoying, and quite unavoidable.

We can now turn our attention to the Numbers tab. The default settings will be adequate here.

In the Strings tab, we have to do something ugly. Check the two items:

• Double quoted strings are always 1 char long
• Single quoted strings are always 1 char long

This is necessary because Logo doesn’t have the typical kind of string constants we have grown to expect in other languages, so we need to trick it, otherwise nearly everything will look like strings. This solution is not ideal, but it is readable. Sometimes, unusual language features will not map to SlickEdit’s default color coding engine, and you have to settle for the best you can do and move on. This is one such case.

The default settings are fine for the Language tab, so let’s move on to Comments. Logo has one type of comment, the semicolon. So, click on “New Line Comment…” and specify that it uses “;” as the delimiter.

We are now done with configuring color coding. Color coding definition are saved in “user.vlx” in your configuration directory. I recommend opening “user.vlx” and copying the entire definition for [Logo], then saving it to a new file “logo.vlx”, also in your configuration directory. This will be used later when we package up the language support.

Step 3: Tuning language settings

We can now configure other Language specific options for Logo. Start with the Indent options. You will probably want to set your tabs to “+3″, or something more in line with your preferences.

Now switch to the Comments options. Define the “Comment line” to use “; ” on the left so that you will be able to use “Document” > “Comment Lines” and “Document” > “Uncomment Lines” in your Logo source files.

On the General tab, make sure “Logo” is selected as the Color coding Lexer name. I also recommend turning on the “Current Line” check box to highlight the current line, since SlickEdit does current line and selection highlighting better than any editor out there.

While we are on the General tab, click on “Language-Specific Project…” to set up a command for loading and running Logo programs in MSWLogo. Go to the “Tools” command and select “Execute”. Enter “logo32.exe -l %f” for the Command Line, and specify the Run from dir to be “%p” (file path). You may have to give a [quoted] absolute path to logo32.exe if it is not on your regular path.

Step 4: Configure aliases

Switch to the Aliases options for Logo. This will allow you to define some typing shortcuts for Logo syntax. I will provide one example and let you go from there.

To define an alias for defining a function, click on “New…” and name the alias “to”. Fill in the alias text with the following:

“%\c” specifies a cursor landing and “%\i” specifies indentation.

Step 5: Create a language support module

All of the above work displays how you can add support for viewing color coded files in SlickEdit, entirely through the configuration dialogs without writing any Slick-C code. However, if you want to hand what you have done over to another developer, the best way is to write a language support module that he can simply load and use. For what we have done so far with Logo, the essentials can be accomplished with the following small amount of code. A complete copy of the language support module (logo.e) is attached to this article.

Step 6: Write tagging support for Logo

Tagging is not rocket science, you can write your own tagging support with a minimal amount of effort, depending on the language you are trying to parse.

In the case of Logo, the critical item is the “to” statement, which defines a procedure.

User-defined tagging support is accomplished by writing a language-specific “proc-search” function, the signature for this function is as follows:

The function returns <0 on error, and 0 on success, also setting “proc_name” to the encoded information about the symbol which was found.

The basic outline for a “proc-search” function is to start by searching for a regular expression which will find lines that symbol declarations happen on. If the search fails, return the failure status and it’s all over. Otherwise, you parse apart the line and get the name of the symbol that was declared. Finally, you set proc_name and return 0. A very simple example for Logo is included below. The “logo_proc_search” included in logo.e is a little more thorough than this, but this is a good starting point for nearly any language.

If you want to support tagging local variables as well as globals, you will need to implement the “list-locals” callback. It’s signature is shown below. The implementation is quite similar to the “logo-proc-search” above, except that rather than working in a start and stop pattern, the list-locals function is just expected to find everything and insert the symbols directly using the tagging API function tag_insert_local2(). I will not detail it’s implementation in this article — please take a look at logo.e to learn more.

Step 7: Adding support for block matching

For many languages, the default block matching which supports parentheses, braces, brackets, and configurable begin-end pairs is adaquate. For other languages, you may want to do more. The prototype hook function for implementing advanced block matching is below. For an excellent example of how to implement this function, look at ada.e.

Step 8: Adding support for syntax expansion

The typical way to add support for syntax expansion is to write commands to handle [space] (syntax expansion) and [enter] (syntax indent). A simple example of this can be found in modula.e. By using the “ext_keys” event table, your language-specific space and enter handlers will be automatically hooked in. For this sample, I am not going to write syntax expansion for Logo — I leave that as an exercise for the reader.

Step 9: Adding support for Context Tagging®

There are six major hook functions necessary to implement support for Context Tagging for a language. Again, I am not going to implement all of these for Logo, but leave that as an exercise for the reader. There are numerous examples in the Slick-C® code of how to implement these functions for a variety of languages. Look at csymbols.e for examples of how they are implemented for a conventional language such as C++. Look at cobol.e for an example of how they can be implemented for less structured languages where you can have function calls without parens, for example.

This function is used to automatically build a tag file for language-specific libraries and built-in functions. You can create a [lang].tagdoc file to document built-in functions. Look at [slickedit]/builtins/basic.tagdoc or html.tagdoc for some examples of how this is done. The attached Logo sample attempts to build a tag file for Microsoft Windows Logo. Note that there is a small problem, because most of the files in their run-time library are extensionless, thus, not recognized immediately as Logo.

This function is used to get information about the code at the current buffer location, including the current identifier under the cursor, the expression before the current identifier, and other supplementary information useful to Context Tagging. If the _[lang]_get_expression_info hook function is not implemented, the editor will use a default implementation which simply returns the current identifier under the cursor and no prefix expression.

Find tags matching the identifier at the current cursor position using the information extracted by {@link _[lang]_get_expression_info()}. This callback is used for symbol navigation, symbol completion, references, and symbol analysis.

Insert tags into the list members tree control matching the given identifier and prefix expression.

If the _[lang]_insert_context_tags() or _[lang]_find_context_tags() hook functions are not implemented, the editor will use a default implementation which simply tries to find a symbol matching the current identifier under the cursor, ignoring any prefix expression.

The _[lang]_fcthelp_get_start() callback is used to find the start of a function call. This determines quickly whether or not we are in the context of a function call. The _[lang]_fcthelp_get() callback then does all the heavy lifting to find the matching functions and parse out their parameter lists and set up all the information in order for the function parameter info feature to display a prototype for the current function.

If the _[lang]_fcthelp_get_start() and _[lang]_fcthelp_get() hook functions are not implemented, the editor will use a default implementation which simply assumes that function parameters are comma-separated lists surrounded by parenthesis.

Step 10: Creating a redistributable hot fix

An easy way to redistribute a set of macros and support files is to package them together using SlickEdit’s hot fix mechanism. To package a hot fix for the Logo support all you would have to do is use the create-hotfix command from the SlickEdit command line. Note that this command requires you to have the Cygwin “zip” utility on your path. You can also construct a hot fix manually by creating your own hotfix.xml manifest and dragging files into a zip file.

The Logo support can be loaded by going to Help > Product Updates > Load Hot Fix… and pointing it to the addons_se13000_logo.zip file.

Summary

This article gives you an initial glance at how to add support for a new language to SlickEdit. It does not detail every single aspect of adding language support. There is still a great deal for you to learn by studying some of the language support code shipped with SlickEdit, such as basic.e, awk.e, ansic.e, pascal.e, modula.e, and fortran.e.

Zip file can be found here

I worried for him while he was telling me about this, and at the same time my mind was half zoning out thinking about my own career. I’ve been in a similar situation… it’s not uncommon for companies to just run out of funding or to have massive sweeping layoffs. The last company that I was at out ran out of money and we all showed up at our office one morning to find movers disassembling our cubes. No prior warning, nothing. Let me tell you, there’s no cup of coffee that can wake you up quicker than the sight of that.

“I just don’t know any other company that’s doing this kind of work,” he continued.

Apparently chem development is not the kind of generic skill that can be easily ported from company to company. I forget sometimes just how lucky I am to have a skill set that is so adaptable. Programming work is so readily available it’s ridiculous. A quick search on monster.com or dice.com will show that there’s a constant need for decent programmers. I say decent because you don’t even have to be a top shelf developer to enjoy this kind of programmer’s market. Most companies are looking for a programmer that can just get a job done. Now, ideally, I try to look for a lot more than that in a job position, but if it came down to being a worker-bee programmer, the money is still good for those jobs and you get to stay on point with your skills. It’s not a bad deal, and there’s always a need for this kind of work.

“The only other pharmaceutical company that has the kind of equipment I work with is two states away, ” he told me.

Again, my brain is thinking about this and wondering what things would be like if my work depended on some niche, specialty apparatus. As a programmer, I’m spoiled by VPNs, remote desktop, portable laptops, 4 gig flash drives and a whole arsenal of gear to help me work from wherever I need to. My friend would have to buy some multi-million dollar research equipment to do his work from home. However, I can connect to my desktop and work from home like I’m right at my desk. The kind of flexibility that gives me is just incredible. How many people are fortunate enough to be as productive from home as they are at work?

“Without being around the lab every day, my skills are going to fall apart… this just isn’t the kind of stuff I can keep up with outside of a workplace,” he told me.

Software developers don’t need professional work to keep their skills up to date. There are many online communities, sites dedicated to providing samples for all aspects of programming, open source projects, and endless opportunities to stay on the cutting edge of software development. Staying current in this way is something many developers do on top of their normal job anyway. It’s not very often that I realize that without those resources, it would be much harder to keep up with all of the change and fluctuation that the software world goes through.

Of course, after all of the things my friend had told me I couldn’t say any of these thoughts I was having. But in the back of my head, I had a real face-to-face moment with the fact that I may be one of the luckiest people in the world simply because I write software. Do I ever worry about losing a job? Sure, everyone does to some degree. Nothing is certain. But I do know that if I ever lost a programming job, I’d have another within a week. No worries.

What does make me lose sleep some nights is what would happen if software development simply went away. It sounds ridiculous, but it’s something that I think about from time to time. Industrial workers in the early 20th century probably never imagined being replaced by robots, but it’s happened on a large scale.  Without software development, I would be in a lot of trouble. I wouldn’t be able to work from home if I needed to. I might have to do something 8 hours a day that I didn’t enjoy doing. I might have to wear a suit.

Even worse, I might have to take a job that didn’t allow me any creative thought. That would be worse than the suit. To have to work at a job where I performed some task over and over, or had some responsibilities that didn’t allow my mind to wonder “What if?” would kill a small part of me. This may be the biggest perk of all in this career choice of software development… the freedom of creativity.

I’m going to spend the better part of today reminding myself of just how lucky I am that there is such a thing as computer programming and that I just happen to absolutely love doing it. When I think about what my life would be without programming, I realize that the stars have aligned in some miraculous way for me.

Here’s my story.

It all started a “few” years ago to when I was in high school. The Rubik’s Cube popularity had just peaked and our school was still just getting computers. I forget the exact specifications of the machine, but I think it was a TRS-80 Model III with about 16K of RAM and no color. I spent a lot of time on that machine because it was old even then and usually free. Most others wanting to use the newer Apples that had color. Wow.

So how do you represent a colored cube on a monochrome display with at best crude graphics? I used letters for the different colors (B = blue, R = red, G = green, O = orange, Y = yellow, W = white) and unwrapped it on the screen. (Fortunately none of the colors started with the same letter.) You would have something like this for a completed cube:

After typing in your sequence of letters representing the colors (You only had one chance. One mistake, and you had to start over.), the program dumped instructions to the printer (”Red Right” “Green Left” “White Around” “Blue Left” etc.) while the arrangement of letters on the screen was updated at each step. Needless to say, it was virtually impossible to take a mixed-up cube, type it’s arrangement into the TRS-80, then follow the instructions from the printout and actually solve the puzzle, but I know a few classmates certainly did try. I really should have made it pause after each turn, so you could check for mistakes as you went.

Here are a few things I remember about the program.

1. I knew the limits of the machine’s memory so made use of the space compression codes. The TRS-80’s BASIC interpreter used the character values from 0xc0 and up to represent sequences of blanks. One byte could be used to display up to 64 spaces. My data structure was one string holding just the letters and space compression codes. I updated the display by printing just this one string.
2. Each of the 18 different moves would change the positions of 20 letters on the display or 20 characters in my string data structure. These character positions were stored in strings of 20 characters. This was much more compact than reading DATA statements. But you couldn’t type these strings with the keyboard because some of their values needed to be higher than the ASCII value of ‘Z’. So I first wrote some code that found the memory location of the array of strings and then used POKE to write the proper values directly into the memory of the program’s instructions. This trick actually made the program manipulated itself.
   I don’t really remember why I did it this way. It did make the program shorter and the code simpler in some places, but I doubt that was the real reason. I think I did it just because I could. Plus is looked cool when you listed the program on the screen. It would beep, clear screen, and show graphical characters inside your program listing. This was a great way to show off to the older junior and seniors when they came in and kicked you off the computer so they could write their boring programs to convert Celsius to Fahrenheit for their computer class. I’m sure they all hated me.
3. Finally, it was my own algorithm. There were a slew books out then to teach you to solve the Cube, but none of that cheating for me. Of course, that also meant that the list of “Yellow Left” “Orange Around” “Green Right” “White Left” etc. probably went on much longer than needed. But that didn’t matter, because you were never going to solve an actual Cube with the program anyway. It was all just a young kid’s way to use up free period.

Best program I ever wrote!

Why is he having so much trouble using my editor? Because I’m using SlickEdit. What does he use? SlickEdit.This scenario happens a lot to me, really anytime a coworker tries to use my machine. Even after he gets used to the color scheme and whatever tool windows I use, if he doesn’t happen to use the same emulation that I use, he’s hosed. He spends more time trying to get somewhere in the code than he does actually making any changes. And no doubt he’s got some custom keybindings on his machine that he uses all the time, but my editor seems to think they have completely different functions.

So the good thing about SlickEdit is that it’s incredibly customizable. You can set it up to do whatever you want, however you want. You can go over, under, around, and through your code using commands and keybindings that you define, and after using them for a couple of days, you’ll feel like you were born using Ctrl+W to comment a line of code. You’ll do all this without thinking about it, because you’re thinking about the code instead of the use of the editor.

Ah, but then you have to use someone else’s configuration. It’s worse if they’re looking over your shoulder, giving you keyboard performance anxiety. You’re all thumbs, two left hands, a DVORAK user in a QWERTY world. Your customizations are your crutches, and you have to limp along to solve a stupid problem when you know it works perfectly on your machine.

In fact, you work perfectly on your machine, too.

Between contract work and full time work, I’ve worked at a lot of places. There have only been a few that I can say I really loved. Interestingly, the characteristic that all of those places had in common wasn’t interesting work or free food or a ping-pong table. It was my managers.

There are good managers and bad managers, and most programmers can say that they’ve worked with a representative from both groups at least once. However, there’s also a class of top-shelf managers, and they’re the ones I’m talking about here. They have the ability to lead a team, and at the same time make you feel like you’re one of the most important people on it.

Quarterback vs. software manager

Whether you like him or not, most of us (at least in the States) know who Tom Brady is. I wouldn’t normally look at him, or any sports star, and see a clear comparison to the world of software development. However, I recently read an article in Sports Illustrated by Ross Tucker about his time spent playing on the Patriots with Brady:

During my time in New England I worked as a backup lineman and often had to snap to Brady while playing center. In spite of all of the other chaos that he had to sort through, he always found the time to look me squarely in the eye and say, “C’mon Ross, me and you, let’s get a great snap first.”

I never wanted to snap a ball so well in my life.

I was a veteran in my fifth and sixth years in the league while in New England and I had started over 20 games, but Brady’s ability to single me out and make me feel important for the success of the play was unlike anything I had experienced.

That’s powerful stuff. I instantly recognized it as the common characteristic of the jobs I’ve loved working at… managers that practiced the same philosophy as Tom Brady. After reading this, I realized that the need to be recognized as an important part of the team is something universal, regardless of your job or your level of experience. It’s about taking people who work hard and finding ways to make them feel important to the team effort. That includes contractors, junior developers, everyone on the team.

So managers, listen up! Yes, programmers like free food. We like the latest and fastest computers. We like ping-pong and pool tables and a fun atmosphere to work in. But most of all, we like to hear that our ideas are important… that our work matters. So often, we are just looked at as the staff that makes the requirements happen. Sometimes it can seem like we are simply a means to an end, but we are so much more than that. Software developers are creative writers; the designers that make your applications work, the same applications that run your business.

If you give a development team a set of requirements, you hope to get an application that meets those requirements. However, when you let the developers participate in the creative process, and make them feel like their contribution is needed, you’ll probably find a development team that will think up and implement features you couldn’t even dream of. All it takes is trust, and an occasional reminder to development that they are an essential part of the process.

The free pizza doesn’t hurt either…

April Fool’s Day was last week.  We had a pretty good April Fool’s Day post here, but I am not certain how many people got it.  This got me thinking about some of the better office pranks I have seen in my long tenure here at SlickEdit.  Actually, I do not think any of them happened on April Fool’s day.  But then its always April Fool’s Day here…

• Fun with peanuts – We’ve all seen the emailed pictures of this sort of thing.  A cubicle “door” is closed off with cardboard, and the cubicle is filled with packing peanuts.  There weren’t enough peanuts to completely fill the area, but I felt this performance was special for a couple of reasons:
  • This an open area with multiple cubicles, so rear walls (whose sole purpose was to hold in the peanuts) had to be constructed.
  • The Enter key was removed from the keyboard and dropped into the peanuts.  This part, was just plain mean.  A Starbucks gift card was also dropped in to soften the blow.
• Fun with Shrink wrap – An office classic.  Various times multiple items on a co-worker’s desk have been shrink wrapped.  There are a few fun variations:
  • Shrink wrap the telephone, and call the prankee as they are unwrapping the items on their desk.
  • When a member of the support staff left for some time to get married, everything accessible on his desk was shrink wrapped.  Since we had the occasional office cookout that day, foil was available and the shrink wrapped items were then wrapped in foil.  Finally, the desk was wrapped in foil.  The look on the face when first foil was removed to reveal shrink wrap: priceless.
    • We have not figured out how to shrink wrap an LCD display.
• Rickrolling – Rickrolling was all the rage around the office a while back.  This is where a link in an e-mail appears to be one thing, but is actually a link to a Rick Astley video.
• The ol’ Box On the Desk – I no longer remember who or when, but one time after a vacation somebody came back to find their desk packed into a box.  I always felt this was a little too mean.
• Moe’ing a Cube – One time a coworker returned from a few days off to find his cube covered in wrappers from Moe’s.  For good measure, a CD player was hidden under his desk playing the “Welcome to Moe’s” sound clip over and over.  I still have the CD.
• Mac on the Desk- At some point a co-worker had some Mac experience, but was hoping he would not be asked to work on a SlickEdit Mac port.  He returned from vacation to find a Mac SE30, a Mac OSX CD, and note “We need to talk – <managername>”.  Obviously, it looked ridiculous.
• A Call From a User- When a member of the support staff was leaving to take another job, we arranged for a user who had called support a lot to call and claim he had an absolutely ridiculous problem.  The subterfuge lasted until we could be heard laughing around the corner.

That is all I have.  Let’s hear yours.

My first job as “the VB guy”

I graduated with a masters in CS, and my research involved working with the Air Force on a neural network algorithm they were implementing. This was all done in C++ and by the time I graduated, I was proficient in the language. My first job was at a startup with 3 other people, where we needed to get something done very quickly and we used VB4 (the latest VB at the time) to write the entire thing. I had never worked in VB before, but I picked it up quickly and learned how to push it to the edge of what it could do, which was a lot.

I remember being blown away by how fast we could test ideas and write new parts of the system, compared to the work I had done in C++ before. VB didn’t have inheritance and of course it had its own quirky syntax, but the power of how fast you could get things done was amazing.

That project went extremely well and we got an enormous bid to continue our work. At that point, I was firmly rooted in my place as a developer of the initial product and would continue developing it. However, we needed to start writing our own device drivers for new peripherals that we needed to interface with. In came the C++ programmers, and shortly after, I became known not as the lead programmer of the main product, but rather as “the VB guy”. As the VB guy, I was always pretty far outside of the C++ clique, even though a year before I had considered myself a proficient C++ programmer.

It’s a scar I think I still carry to this day.

Any idiot can program [insert high level language]!

Anyone who has worked for a significant amount of time in VB, Ruby, Perl, or even C# and Java probably knows where I’m coming from. There is a large number of people who hate these languages purely because they allow newer, less experienced programmers to develop working code quickly. You don’t need to know what a pointer is to program any of these languages. You don’t need to know how memory is allocated for new objects, and for the most part you don’t have to be conscious of freeing it either. You don’t need to understand a lick of the Win32 API to make a working client application in VB. The list goes on and on and on…

There are also programmers who have battle wounds from debugging memory leaks from unfreed pointers. There are those that learned to program Windows applications from Petzold’s book where you wrote the WinMain function and the message loop by hand. There are programmers who learned COM by hand writing their own implementation of QueryInterface and doing their own reference counting. Many of these programmers watch in horror as new, inexperienced programmers get the same end result in a small fraction of the time because their higher level language wraps up what they’ve spent years mastering, and makes it “just work”.

Check your ego

I believe that’s where so much of today’s language bitterness comes from. All programmers strive for higher levels of abstraction and functionality, whether it’s through libraries or frameworks. However, there’s a level at which the programmers who understand what happens internally start to despise the programmers that make use of that abstraction without understanding those internals. It’s a smug, arrogant attitude that makes a developer believe that they are a better programmer, or that their language is better, because they work at a lower level. Unless you are writing your code in 1s and 0s, there is always a huge amount of “scaffolding” underneath you that you just rely on.

If you’re one of these people, get over yourself. There are both great and terrible programmers in every language. There are brilliant VB programmers and there are frighteningly bad C++ programmers out there. If you resent beginner programmers being able to write apps quickly in VB, or put together a web site quickly in Rails, then you need to seriously rethink what the point of programming is in the first place. Their success should be your happiness.

This is a pretty common programming scenario which can become quite unnerving when you discover that the original function was named perfectly. Of course, you can’t reuse that name because you are programming to a C ABI, or the signature is not different enough to allow you to overload the function.

So, you spend the next half hour of your day figuring out a name for this new function which makes sense. Here is one example, the original function:

   int findMatches(string regex, int flags);

And the new function changes the meaning of one of the flags. So you name it:

   int findMatchesWithNewFlags(string regex, int flags);

But wait, that’s a pretty stupid name, and rather verbose. So you try to capture what is really different about the new function.

   int findMatchesOldReentrantFlagIsReverseFlag(string regex, int flags);

Still pretty verbose, and if we change the function again in the future, this will just get silly. OK, how about this:

   int findMatchesWithReverseOption(string regex, int flags);

This is better, but still verbose. There has to be a better way.

Generational Naming Conventions

Well, on this day of April 1, 2008, let me share with you the dearest naming convention to my heart, generational naming. In this paradigm, we recognize that the original name was perfect, so all we want to capture in the name of the new function is that it is newer. You do this by adding a “2″ to the end of the name.

   int findMatches2(string regex, int flags);

When you need to again change findMatches(), you create the next generation:

   int findMatches3(string regex, int flags);

Extended Naming

There are several less powerful variants of generational naming. For example extended naming, where you add “Ex” to the new function. This is in fact, a common practice at another large software company located in

   int findMatchesEx(string regex, int flags);

And then there is “new naming”:

   int newFindMatches(string regex, int flags);

Which can actually be extended twice over:

   int newerFindMatches(string regex, int flags);
   int newestFindMatches(string regex, int flags);  // buck stops here

Conclusion

The conclusion is simple. You do not need to be smart or clever to write code, you just need to know how to count.

Learn to write well. [*]

“But that’s not a programming skill!” you’re probably saying. Or maybe you’re disappointed because you thought I was going to be talking about the very latest cutting-edge API you can’t live without. Good writing skill is probably one of the most useful talents you can develop as a software engineer, and ignoring it is one of the biggest mistakes most programmers make.

Working in a cave

I used to work with a programmer who we jokingly referred to as a “walking MSDN”. He knew all the Win32 APIs, he could tell you the int values of const definitions and could enumerate the parameter lists to functions overloaded 30 times over. As a programmer, when given an assignment, he would go into his cave, hammer out a solution and would re-emerge from his cave with something that worked. I mean that in the most serious way… he would hammer his code into submission until it worked. There was no such thing as elegant code to him; it worked or it didn’t.

His manager both loved and feared him because he would do everything required on time, but he had no idea what happened in that cave. There was no visibility at all into what he was doing, and his manager had to blindly rely on the fact that he had a history of getting stuff done on time.

Programmers loved and feared him because he was incredibly knowledgeable and could answer any question about how this or that API worked. But whenever someone had to get inside his code, it was a pure mystery. There was no documentation, no models, no code comments… nothing but the raw code itself. For mister MSDN, this was no problem, because it was all in his head. For everyone else, it was like being lost in a big city with no map.

Was he a good programmer? Most people that worked with him would say yes… he was technically proficient and met his deadlines. But most of those same people would also say that they had a very difficult time working with him. That element of fear that he generated was a direct result of not being able, or willing, to communicate. He couldn’t communicate his plans or designs to other programmers. He couldn’t communicate his status with his managers. He couldn’t communicate his interfaces with other teams. Eventually when he left, his code left a wake of terror felt by those that had to pick up where he left off.

The lifespan of a tech skill

Technologies come and go. Seven or so years ago, I felt like I was completely on top of my game when it came to programming technology, at least in the Microsoft world. I had a very deep understanding of COM and ATL, thanks to Chris Sells, Brent Rector and Richard Grimes, and I coupled that with VB6 on the front end. This was a really potent combination and I thought I’d be working with that for years and years. But, as with most technical skills, it didn’t last long… .Net came along a year later, ATL became outdated and VB6 just disappeared into the sunset. Now that I’ve mastered C#, I find that I haven’t even touched the new stuff in .Net 3.5. The point is, no matter what technology you learn, with very few exceptions, it will disappear or be overshadowed by newer technologies (and probably sooner than later).

Writing skills will last you a lifetime, though. You will always benefit from it, regardless of what language or technology your use, or whether you’re even a programmer or not. Good writing skills are universal and will never be replaced.

The golden rule of documenting software design

Try to document whatever you are working on. It doesn’t have to be the worlds most perfect UML and you don’t need an expensive tool to do it. In fact, Wordpad and Paint are sufficient, and don’t tell me you don’t have those. Write in a way that best expresses your intent and your thought process in coming to the design decisions you did. I have a golden rule of documenting software design:

Describe your design to others as you would have others describe their design to you.

When you spend the time to do this, you’ll find that many benefits will follow. You’ll get feedback from others that may have tried to solve a similar problem and have insight you may not have thought of. You’ll leave a clear trail to follow for those that work on the code after you. Most importantly, you’ll shed light on your work, which everyone who depends on your work will appreciate. Even if no one else reads what you write, you’ll still have worked through problems in your head that can only lead to better design in the long run. There is no downside to documenting your designs.

If that wasn’t enough, consider the fact that someday you may be looking for another programming job. You’ll sit down with other developers and managers in an interview and try to describe how great your technical abilities are. You are now one of the vast sea of programmers trying to get that job. With your resume alone, a company has only your answers during the interview to base their decision on. With your documentation in hand, though, you can show them in full detail the type of work you’ve done and give them deeper insight into your thought process than they could ever get from interview questions alone. Your documentation serves as a body of work that travels with you, long after you’ve stopped working on this or that code, and speaks for your experience.

Of course, these skills won’t write code for you. But think about how much time you’ve devoted to learning programming based skills. Think about how many books you’ve purchased and read about programming. It’s a huge investment in time and money to keep up with. The next time you have some free cycles to sit down and pick up something new, consider skipping the software development section of the bookstore and pick up a book about technical writing. Here are some good books on this subject:

• Writing White Papers: How to Capture Readers and Keep Them Engaged
• Developing Quality Technical Information: A Handbook for Writers and Editors
• Documenting Software Architectures: Views and Beyond

I feel like I’ve gotten to know you, that you’re not just a program or a set of files. You have a personality that I spend most of my day with, sometimes more than the people I work with and even my own family. We have our ups and downs. We’ve had days where we hated each other, and you were so stubborn that I wished I had never written you in the first place. But we also had times that made me feel like one of the proudest developers in the world. We learned a lot together and sometimes your bad behavior taught me something new about the way I write software. At other times you’ve amazed me with the things you’re capable of doing, producing results that were useful in ways I’d never originally intended, as if you were secretly developing yourself while I wasn’t looking.

There are going to be users out there and most of them are great people who will be excited to buy you and work with you. But there will also be some that won’t be so nice, and they may say or blog really bad things about you. You may be installed into environments where you have no clue. People aren’t going to be so gentle with you in the real world. They won’t be forgiving when you make mistakes and won’t give you the soft restart that you’re used to when you get debugged. I’ve tried my best to give you everything you need to avoid those situations and handle them gracefully, but sometimes unexpected things happen. Just remember all the good things you can do and let the bad stuff go.

We’ll be seeing each other from time to time, during bug fixes and maintenance, but it won’t be like this last development cycle. I hope I’ll be able to keep improving you and making you the best you can be, but in reality I’ll have new features to work on and a schedule that only allows us so much time together. I know my new features… they’ve started just like you did, some of them as ideas that came to me while I was writing you. But no matter what features I may work on in the future, the time we’ve spent in development together will always be unique and I’ll always remember it, just as I remember the features and programs that came before you.

This will be a milestone build and release and I can’t wait for your introduction to the world. Remember that I believe in you more than you know. Now get out there and show everybody what you can do!

Today, I want to discuss a common problem that occurs after the estimate is delivered. Often, the estimate is considered to be too high and management tells you how long you have to complete the task. Sometimes this is motivated by important business goals. Other times it’s motivated by a manager who wants to look good or has a bonus tied to a delivery date.

Regardless of the reason, when the team is given the new timeframe they have to scramble to meet it. Often, teams cut corners to try to hit what is, otherwise, an impossible deadline. This has happened to me on a couple projects with what I know now as predictable results. To illustrate it, I offer:

The Parable of the Loaf of Bread

In a land far away lived a king who was terribly fond of bread. He ate bread at every meal and would often request it as a snack. One day the king requested some bread, but he was told by the royal baker that they were out. Apparently, one of the apprentice cooks had used all the remaining bread to make croutons.

“Off with his head,” yelled the king, not at all pleased that he couldn’t have some bread. “Now, how long will it take you to get me some bread?”

“Good King,” replied the royal baker, “I can have a nice, hot loaf of bread for you in about 2 and half hours.”

“Two and half hours!?! Not good enough! I want bread sooner. Bring some bread in an hour or you will share the fate of your apprentice.”

The royal baker returned to his kitchen, determined to meet the king’s deadline. But how could he do it? Every good baker knows that it takes 10 minutes to mix the ingredients for the dough, 15 minutes to knead the dough, an hour to let it rise, and then another hour to bake. How could he finish in an hour?

“There’s nothing I can do to mix the ingredients faster,” he thought. “But maybe I can let it rise for a shorter time. And maybe I can bake it quicker if the oven is hotter.”

So he set about to make the loaf of bread, cutting corners wherever possible. He placed the bread in the oven after letting it rise only 20 minutes. He thought to himself that that loaf looked small, but hoped it would come out OK. After 30 minutes he removed the loaf from the oven. The outside was too dark from the higher temperature, but it didn’t look burned. Maybe this will be fine.

The royal baker rushed the hot loaf up to the king without a minute to spare. The king sliced open the bread to find that the crust was way too hard and the inside too dense and not at all cooked.

Thoroughly displeased, the king looked at the royal baker and asked, “What is this? This is not a decent loaf of bread!”

The royal baker replied, “Good King, I did my best to bring you a loaf of bread in the time you allotted, but this is the best that could be done.”

“How long will it take,” inquired the king, “to bring me a decent loaf of bread?”

The baker thought for a moment, but there is nothing he can do to shorten the amount of time. “I can have a nice loaf of bread for you in about two and a half hours,” he replied.

“Two and a half hours!?!” yelled the king. “I already gave you an hour. So bring me some bread in an hour and a half or I’ll cut your head off.”

The baker returned to his kitchen, highly motivated to give the king what he wanted. Try as he might, he could think of no way to bake a perfect loaf in the amount of time given. So, he took the uncooked center from the first loaf and added in a bit more dough. He didn’t have time to let it fully rise and he had to cook it for less time than it should, but it was the only way he could produce a loaf in the allotted time.

At the end of the hour and a half, the baker returned to the king with the new loaf of bread. Again, it was overly done on the outside. The inside was a mixture of dry, dense dough and underdone dough.

The king was furious and called the guards to have the baker executed. He had the assistant baker brought before him and asked him how long it would take to bake a nice loaf of bread. The assistant baker, clearly unnerved by the fate of the former head, now headless, baker responded, “Your Majesty, I am aware of your desire for some nice bread. However, there is nothing I can do to speed the process and produce a loaf that is worthy of your Highness. I can bring you a nice loaf of bread in about two and a half hours, but I could make you some delicious rolls in about half that time.”

The king mulled it over for a few moments and said, “Very good. Some rolls would be nice.”

The End.

In software development, this cycle is all too common. A deadline looms and we eliminate steps that we know are essential to producing quality code. We throw out unit testing or greatly reduce the number of tests produced. We eliminate design and code reviews so we can spend more time writing code. I’ve even seen projects curtail analysis and design thinking they can adapt as they figure out the fine points later.

The problem with this is that cutting corners produces poor software, often with a high rate of defects or a design that can’t be extended or modified to meet changing requirements. As the code base grows and has more of this low-quality code, every subsequent unit of development takes longer than the ones before it. Rather than providing the basis to speed subsequent development, it slows it down as you are forced to trace problems and limitations in work that was previously “done”.

It’s hard to get non-developers to understand the impact of using poorly written code. But it is as clear and obvious to developers as attempting to use a half-backed loaf of bread to jump-start the creation of a new loaf. So it’s important to push back and try to educate your partners about what they are asking you to do.

Explain the risks involved and why essential steps can’t be skipped. I’m not saying that you should be a purist. Be pragmatic and willing to bend. When your back is against the wall, you should look for ways to perform steps, like unit testing, as quickly and efficiently as possible. You may find that the business need warrants the risk of skipping unit testing on infrequently used or less complex code paths.

Try to get them to reduce the scope of what is planned, just as in the parable when the assistant baker offered rolls instead of a loaf of bread. Cutting features is the surest way to shorten a schedule. Even if you don’t get permission to drop features, work on the code in an iterative and incremental manner. Get the essential functionality finished before adding bells and whistles, even if you’re told you can’t ship without them. When they’re given the option of shipping without them or shipping nothing, you’d be surprised how often they are willing to leave them off.

Hopefully, your project is a team effort and not a monarchy. Just as there are development considerations that they may not understand, there may be business considerations that you don’t understand. Work together to define an acceptable level of risk and then perform your development accordingly.