There is NEVER one person working on your code

Alternate Title: Avoid “Black Boxes” and “Works on my Machine”

Even when working on a project by yourself it is important to try and create a build script that will “fully” build your project with a single click. But, you may be asking, why would I bother with a build script if there is only one person working on the project? Well the reality is that there is NEVER one person that works on a project.

There may only be one person working on a project at a given point in time, but if the project succeeds (a.k.a. it has additional releases in the future) there will be other developers involved. Either a future developer will work on the project on their own, or additional developers will join in. I’m of the opinion that the latter is far more likely if a build script already exists and those other developers will thank you (as would I) that they have some transparency into how the code should be orchestrated for a deployment or in other words avoid the “black box” problem.

In addition to just a build script that compiles and perhaps packages for release, a helpful goal that I think a developer should strive for is to attempt to create a package (a.k.a. source code and build script) that can be checked out to any machine and be built immediately. With the caveat that the build tool (a.k.a. nAnt, Bash Script, etc.) is a pre-requisite of building. Alas it’s impossible to have 0 pre-requisites for most build processes, i.e. the OS already has the build tool installed, except for things like a batch file approach to build scripts, which I’m not a fan of. By attempting to achieve this goal a developer helps avoid the “works on my machine” syndrome that is often present when only one or two developers ever work on a project and there is no build script present. It is also VERY helpful for “the new guy” joining the project. I should note that I specifically stated that a developer should “strive” to achieve this single check-out/single click build because often there are some pieces that will require pre-setup or local dependencies to be installed prior to building, such as DB clients or third party plugins. By attempting to achieve the “ever more automated build” goal it can greatly reduce frustration for others down the road.

One last tip to those diving into build scripts, it is helpful to establish a process where the build script is versioned along with the code base. In a continuous integration environment, ideally, a developer can change the build script and check-in and that will trigger a build to ensure that the change to the script did not in-itself break the build.

Help users help themselves with built-in Microsoft tools

Credit to Scott Hanselman for reminding me of this very helpful tool with his blog post entitled Helpyour users record and report bugs with the Problem Steps Recorder. Below are the same highlights from Mr. Hanselman’s blog with a few of my own notes as to additional features of this tool.

When you are technically inclined you tend to get a lot of “support requests” from friends and family. Even at work various colleges may come up with scenarios where they have a problem and would like your assistance with resolving the problem. However, often is the case where the problem is “no-repo” or in normal speak not reproducible, as is often listed next to various items in numerous bug reports. With Windows 7 Microsoft has provided a nice utility that can, hopefully, make it easier for you, the professional geek, to have a user help themselves by being able to provide you with the needed info to reproduce the issue in question.

The name of this fabulous tool is the Problem Steps Recorder (available starting with Windows 7);  this little gem is quite straight forward for any user at any expertise level to navigate. The UI only has three buttons, Start Record, Stop Record and Add Comment. I will mention that there are settings having to do with frame captures and location to drop files, but the default of 25 frames would seem to be plenty and once a user clicks Stop Record they are prompted for where they would like to save the results so I would assume that most users will not need to access these settings.

The shortest way to get to the tool is via the start menu any typing Steps or PSR. The EXTRA LONG way is, Start Menu --> Control Panel --> Troubleshooting --> Get help from a friend (left side of screen) --> Problem Steps Recorder (bottom of screen)

Problem Steps Recorder
available starting with Windows 7

I believe the first two buttons speak for themselves, the third button, when pressed, after pressing Start Record, allows the user to create a rectangular area highlighted on the current screen as well as add a comment that will be added to the final results.

The results are a single MHT file. MHT is short for MIME HTML, which essentially allows a single file to contain both the words and images of a webpage, along with the layout of course. This is then packaged into a ZIP file for easier transport, since the MHT would include the screen shots represented as text the file site can be quite large.

After the user presses Stop Record then can use the drop down arrow next to the question mark and send the an e-mail with the resulting ZIP file attached, dependent of course on the user having an e-mail client setup on the OS.

The results contain quite a bit of useful information, the most direct are the screen shots with notations of the actions the user took as well as the order taken, and this can even be viewed as a slide show. Another useful feature is the “Additional Details” section of the report which shows specific program information and more details about the UI elements being interacted with.

In summary, the PSR tool can be seen as a simple screen capture based on user clicks along with the ability to add notations and detailed results to review later.

Additional resources:

The Deceptive Complex Problem

Complex Communcation arises
when everyone "communcaties" with
everyone else all the time.
A while back, I wrote about the "really big" problem that companies faced and how they were looking to tools like SharePoint 2010 to aid them in solving it. In my post I made reference to an article in Inc. Magazine, written by Joel Spolsky, CEO and founder of Fog Creek Software. The title of the article is A Little Less Conversation and by way of a brief overview, the article explains that when you are working in a group on any given problem its best if the group can be small, and if it can NOT be small then try to keep “control” over the communication channel.

As I’ve pondered on the “really big” problem, a.k.a. Communication within a group, I’ve come to appreciate another perspective brought out in this article, which is that everyone needs to respect other people’s expertise in a specific problem area when working at a large company. As noted in the article, at large companies people tend to be highly specialized, meaning that they focus on a specific domain area, such as Databases, Server Administration, Networking, Security, etc.; however, what I’ve come to appreciate about approach is that it creates a deceptive complex problem in the communication front. Or to put it another way, it creates a “hidden” problem. The reason I say hidden or deceptive complexity is that with all the specialized people it would seem like you don’t need all the team members to really have a complete picture, or do you?

Often people will seem to think that each team member has to focus on their little section of the puzzle and doesn’t need to concern themselves with the whole picture. I don’t mean to say that you don’t want everyone to have access to the full requirements or write-up of what the problem is; however, when you create this segmentation of responsibility it can result in a culture where everyone is “only” responsible for a small section of the puzzle and thus no one is really responsible for the entire puzzle.

So how can you address this deceptive complex problem? As is the case with most problems it would seem communication is the key. When projects begin it is typical to bring in the team to identify what is being done and who will tackle each section; however, it would be unwise to think that a weekly “team” meeting with EVERYONE should be held and the reasons are noted in the article in Inc. Magazine in terms of communication cost. Instead, it would be best to identify where the sections connect and then “encourage” those smaller groups to collaborate on the resolution.

At this point if you’ve worked on software development projects before you might begin to visualize an intersecting web of parts, databases, application servers, web servers, end users, etc. and then the people responsible for the pieces and how they interact and you would perhaps draw the same conclusion that I have which is that as a developer you are the center piece which will require all those pieces to come together. So am I suggesting that a developer should play a key role in ensuring that the communication within a team happens in a meaningful manner? YES.

As developers we should concern ourselves with every piece of the overall solution. Why you may ask, well what does the code we write impact… EVERYTHING. Another  way to express this thought,  is to  ask what is needed for an application to work? At least a single server and CODE (technically you need users otherwise why are you doing what you are doing, but that’s a topic for another post). You would probably like more than 1 server, and it would be nice to separate out concerns like security and networking to others that focus on these areas, but as a developer all the pieces come together around what you are working on, and if you don’t think that you’ll need to communicate effectively to accomplish the evergreen goal of ever developer to “ship the code”, then please connect me so I can steer clear of your projects because I’m fairly certain that you’ve succumbed to the deceptive complex problem.

Good Shoes and Microsoft Outlook

I think I've found my favorite pair of shoes in the latest black slip-on Florsheim shoes that my wife picked up for me a few weeks ago. At this point they are still not broken in and rub my ankles raw if I have them on for any length of time, based on past experience I'd estimate I have a good 4 weeks before they are "comfortable" enough that my feet won't hurt after wearing them. So you may be asking yourself, why is this guy think these new shoes are so great? Because they look awesome, mind you I'm not saying they make ME look awesome. They are simple with clean lines, they have a nice shine, and I really like the way they look. The reason I like the way they look is because I like anything that has a minimalist feel. I enjoy pieces that don't attempt to look good by having tons of extra "stuff" that just isn't needed. This is also something I've found very appealing in the UI for the 2010 version of Microsoft Outlook. In particular to be able to shape the UI so that you only need what is necessary while performing various tasks.

Below are the two views I switch back and forth between while using Microsoft Outlook. Since using e-mail at work is synonymous with breathing it goes without saying that I spend a substantial amount of time using outlook; however, I would guess (meaning I haven't done any actual measurement/testing) that I spend far less time looking at my e-mail. The reason I believe this to be true is because I do not fear my inbox. It is NOT a source of stress for me.

Default view with menus expanded

Reading view with menus collapsed

One way I accomplish "conquering my inbox" is by switching to the "reading view" (as the name implies) when I need to focus on responding to messages. This view allows me to focus on reading my e-mail and responding as needed. When I to organize, archive, setup tasks, manage my calendar, etc. I switch to the default view. However as a rule I DO NOT leave outlook in the default view, so as to encourage focusing on messages as they arrive and not the other tasks as listed previously. This often results in my being able to read and absorb more information from my e-mails.

Just as with code, if the viewing area for displaying lines of code is larger you tend to get a better "overview" of what the code is attempting to do. The same holds true (at least in my case) of the reading pane in Outlook. If you can see more of the e-mail thread at one time you tend to absorb more of what has transpired, this is often helpful when you are looped into a discussion after it has been initiated.

Reading and default view in MS Outlook
To toggle between the two views there are two tiny icons located in the bottom right corner of the window next to the scale slider as depicted in the image here.

Don't leave your users hanging

command prompt can show actions as they are taken
If you create software one of the worst experiences you can create for your users is the "hanging" dialog. Recently I obtained a somewhat older MP3 player; to be specific it is a SanDisk Sansa Express 2GB. The device itself is on pair with most MP3 players that are not an iPod. One interesting feature is that you can record from the radio and it just so happen that the weekend past I had a need to record some audio from an FM station being used to broadcast at an assembly I was attending. To skip to the interesting point I found myself attempting to install new firmware to make it possible to listed to the WAV files created from the recording. After installing something to install something else (can you say inception) I found myself in a state of frustration because it "seemed" like the firmware update was going through just fine; however, the dialog box which indicates the progress had been "seemingly" stuck for quite a bit of time. So as any rational person would do I ignored all the warnings on the screen telling me NOT to remove the device while it is being updated, I yanked the cord out of the plug and started over, after turning my computer on and off again at least twice as any good technician will tell you is critical after just about any action you take. After attempting to install the firmware the "easy" way (using other software from the vendor) I again got "stuck" and gave up. At this point I believed I could overcome the problem by "manually" installing the firmware.

Sansa Updater dialog without any progress (in oh so many ways)
Sansa Express - SanDisk (c) 2006-2008
After jumping through the seemingly random steps of extracting the various ZIP files and installing different drivers and ensuring I held down the "volume down button" (a.k.a. -) while plugging in the device I managed to get back to the same install screen that had haunted me before. Oh, and somewhere along the way I had to format the drive to continue so I lost the file I was attempting to use in the first place.

While weaving through the various steps I realized that I may have cause myself a great deal of frustration simply because I was impatient, but is that really my fault? Well in some small way yes, after all patience is a virtue. However, I tend to think most of the blame rests with the software developers who created such an uninformative update process. If this had just been a command dialog via dos and they just listed of each file being impacted or perhaps a list of actions being taken I may have been more patient. Now to be fair this is a simple firmware update for a seemingly simply MP3 player and so the thought put into making sure a progress bar was accurately capturing the progress of the installation may have been a lower priority, but if there is nothing moving, no blinking indicator that something is still happening it is easy to expect that a user will abandon the cause and move on to something more shiny.

So don't leave your users hanging. Give them the ability to peer into the goings on and inform them of what to expect in terms of responsiveness.

UPDATE: After 10 minutes after writing this post I came across additional information that outlined that the underlying issue with updating the firmware was it had to be done using a windows XP machine. Fortunatlly I have an old laptop with the legacy OS (along with various versions of Ubuntu) so I was able to get everything working and update the firmware, I did mange to lose a recording that I didn't have a back-up of, but such is life.

Why we have to "Ask Why"

I'm always interested to find personality traits that seem to be common to "smart" people. When I use the term "smart" I don't mean to imply that they have some knowledge that is unattainable by others, also I don't mean to imply that they are more intelligent than the average person (although I suspect that if we were going off IQ that could be true). To be clear, I don't typically include myself in the "smart" category, I tend to think that I just happen to have a good memory which gives the impression of being smart, as well as being prone to asking the question why, which I have observed as being a trait of "smart" people.

When people passively accept information that is given them without asking the question why, the result is often that the person receiving the information winds up with only a cursory understanding of the subject matter. In some cases I would completely agree that the "right approach" is to only obtain the cursory overview so as to be able to quickly dive into whatever task prompted obtaining the needed information in the first place. However, it seems to be that too often this cursory understanding becomes the default level for most persons even after the use of the information becomes more critical. To put it another way, after a person gets the "minimum" information to accomplish a given task there is no further effort put into obtaining a better understanding of why "things work the way they do".

In a large enterprise (such as the one I spend my days currently) the end result of NOT asking why is that people go about their jobs doing completely unnecessary tasks simply because the default understanding is to "do it the way the person before me did it". I'll admit that this is probably easier in terms of the mental energy needed to have someone learn a set of tasks; however, I'd argue that anyone who has to complete a particular task repeatedly over the course of many months and perhaps years would benefit from a deeper understanding of what is attempting to be accomplished.

In the case of a developer the need to ask the question why, IMHO, is NOT optional. If you are a developer and you DO NOT ask "why" at least once a day there is a good chance that you are NOT a good developer. It is easy to fall into the snare of believing that getting a good requirement document means that the "why" question has already been asked and answered and you simply need to implement the technical aspects of the requirement; however, this is almost never the case (except perhaps in the most fundamental of features).

At every level of the development process all parties involved will be benefited by having a deeper understanding of asking the question why at each step along the way. In fact there is even a "method" called the 5 whys which shows how asking the question 5 successively (at least 5 times) will help to uncover the root cause. It would be good to note that as quoted by Jeff Atwood (of Coding Horror fame) if you ask why too many times the answer winds up "because there are people on the earth" which is a good indication that you may have dived too deep.

So if you are a developer don't forget to ask why, in fact in life in general it's probably a good idea to remember to ask why, just to keep things interesting.

Perspective and Puzzles

Reversible figures and vase. From Wikimedia Commons
I recently remembered a ted talk from a while back about optical illusions and how our eyes can be heavily influenced by the context of what they see, or as mentioned in the talk, "the light that hits our eyes is not what is important, rather it is what we do with the information once it hits our brain that matters." To help illustrate this point the image here shows a famous "illusion" in that depending on your perspective the black area is the silhouette of two faces, or the white area forms a vase, in reality both are true and it is a mater of perspective on which view is "correct". FYI, I believe depending on how my day is going one or the other is true. :)

I've also been rediscovering the fun I have playing Sudoku. It's interesting how organizing numbers into patterns according to rules fosters a sense of accomplishment. Probably informs my career choice of "professional geek" (a.k.a. programmer).

Sudoku Puzzle. From Wikimedia Commons
That's not to say that enjoying puzzle games and being a good programmer are inextricably linked, in fact I'd dare say that in some sense, being fascinated with solving puzzles can be a detriment to being a good programmer. For example, solving a sudoku puzzle requires a very strong adherence to the rules of the game so that you can "predictive" the combination of numbers in the correct sequence to solve the puzzle. This same strict adherence to the "rules" of programming will result in the idea that given a particular situation there is only one solution which will work; however, as has been proven time and time again in the world of software there are plenty of choices to solve any given problem and often the "right" choice is more influenced by perspective.

I often find that at one level a programmer is a plummer. You connect the pipes and/or tubes if you will. (You didn't know that the internet is a series of tubes?) Then turn on the information faucet and have the data flow from point a to point b and then it all goes down the drain. From this vantage point programming would seem like it's just a puzzle, if only all problems could be that simple. The reality is that the issue is not moving information through tubes, the issue is figuring out if you even have the right information in the first place.

This is where perspective comes into play. You have to be able to obtain the context of a problem and appreciate the subtle shades of gray that come into the black and white world of programming. Who are your users? What are their objectives? How do you want them to feel after they use your software? And a hundred other questions that even make me cringe when I think about attempting to answer these questions for all but the simplest of problems.

If you do figure out what the right "perspective" is then you can dive into the "fun stuff", where you get to enjoy the straightforward challenge of programming and relish the sense of "solving the puzzle, the right way".