Things I wish I'd been told

[tara_hanoi]

In case you haven't figured out from half of my posts, I'm one of the many people involved in the software industry. While most of my job is Quality Assurance, there's a relatively significant development portion as well; such as developing internal tools. Some of these tools are web-based, and some of them aren't.

Over time, I've developed a bunch of habits and tools that are probably so inutterably obvious to the professionals that they don't bear mentioning. That said, there's always a wealth of information for beginners and pros, but very little for those stuck somewhere between. Sometimes academia will teach you grand plan for how something works, but will ignore the basic techniques for writing anything more complicated than "Hello World". I'd like to make a humble effort to bridge that gap (although I think I'm still crossing that gap myself) by sharing techniques that I frequently fall back on in the course of my job.

I really don't know how I want to format this, so I'll go with a rambling list.

1. Learn your method for isolating and identifying failures - As a QA engineer, I need to know this one to do my job. As a result, I've picked up too many techniques to enumerate, but basically it boils down to building a theory of what went wrong, testing that theory, and then taking steps to fix the problem. Many people will sell many techniques (either for money or for mindshare), but you should take none of them as gospel. As time goes, you'll build your own technique, and you'll pick up tips from others. But the basics remain the same: Identify the deviation in behaviour; formulate theories on what caused that deviation; test those theories (preferably in a safe environment); fix the problem.
   
   As a side-note: it also helps to document your progress through your diagnosis in case you encounter a similar problem again. Most professionals do that in a bug report or in some other tool they've employed for the job. Trust me, that saves a lot of heart-ache.



2. Outlines in comments are a good thing - this is how I'm fleshing out my list, and how I did most of my essays in college (and my blogs; if you look carefully you can see the seams dividing something I wrote at different points of the day, or even entirely different days). Yet it came as a surprise to some co-workers, once upon a time.
   
   Figure out the basic steps you want to perform. Write them out in comments. Fill in the code to complete those steps between the comments. If you want, delete the comments later, although I always think that's a bit of a bad idea. But, reading a lot of code blogs, I'm pretty sure people wouldn't like how I comment. That said, these comments are just to remind you what the basic steps of your program are - this allows you to walk away from your program for a while, return to it, and figure out what the hell you were in the middle of doing.



3. Investigate and learn how to use some tools of your trade - Depending on your development domain, there can be a lot of tools available to you, or not very many. No matter, you should take some time to get the lay of the land. One very useful tip, when you find yourself developing in a new domain is to browse around various forums and discussion groups to see what names crop up frequently; chances are you'll do well to become familiar with them before you're forced to do so.
   
   For instance, I had to maintain an internal webtool that relied very heavily on javascript. Mozilla's "view source" only showed the page that it had downloaded, not what it went on to render. For that, I found firebug to be indispensable; it would have taken me a lot more time to understand what was going wrong if I didn't have a tool like that at my disposal.
   
   I still don't use, or know how to use, a good 90% of its features. That doesn't matter, because the 10% I did use did the job I needed.



4. Maintain a 'trinkets' directory - This is a little habit of mine, and I don't know if anyone else does this. I find this works better for scripts than it does for compiled languages, but both are perfectly acceptable; I just find compiled languages require a little more work (so I normally keep a template handy). Trinkets are exactly what they say on the tin. They are small playthings that you use to prove a concept to yourself in some way. In work, I currently have 3 trinkets directories for 3 different languages: c, ksh and perl. I've tidied up a handful of these and I'm putting them up for people to see - Hosted on BitBucket.
   
   Trinkets are useful because they allow you to test something outside of production code. They normally focus on exactly one topic, and just have a bit of other trivial code to show the output of what you're doing.
   
   At this point, I feel I must stress something: TRINKETS ARE NOT UNIT TESTS.
   
   A unit test is testing the functionality of your product, and should be automatable. A trinket is meant to solidify your working knowledge of something. Chances are you'll throw it away after you're done. A unit test should know whether it passed or failed. A trinket is meant to expose some functionality so you can eyeball how it works. A unit test tells you if you've broken something. A trinket tells you if you understand a concept or not. You're meant to play with it, and make it work. It's not any indicator of the quality of your project, it's simply a way for you to solidify something you weren't sure about. Trinkets are a learning tool, not production code.

These are practices that I use when coding. I'm pretty sure the programming community at large will sneer at some of them (namely comment outlines and trinkets), but I think these are really useful, especially for beginners.