In general, documentation is a good idea. We all know what I’m talking about, but why don’t we do it? It takes time, it’s not maintained, and who really reads it anyway? Everyone reads it! Assume that anyone will read the comments you make in your code. It’s a very easy way to get inside someone’s head. Today I was trudging through some code and had to harass our Sr. Engineer countless times to figure out why <insert snippet of code> was there. Half the time I asked he said, “hmmm…I don’t know.” It then took the two of us cruising the codebase to figure out the purpose.

The primary argument against documentation seems to be that the code should be readable on it’s own. News flash- it never is. I may be the brightest coder in the world, I’m not…but go with me, but trying to read the code that other people produce can be painstaking. Hell, I have a hard enough time reading the written language of some people, let alone code. So please, document what you’re doing. You’ll save everyone time.

There are many ways to accomplish the same task. Know this. My solution for a specific problem and yours may be completely different, in fact I would bet that they are statistically more likely to be different. We all have different backgrounds and standards so things will be different. But, that doesn’t mean that you have to ruin any hope that someone can jump into your code.

I’ve worked on projects where the code was like a never ending maze. Sure there are languages that allow you to do some pretty cool things. You have functional languages, recursion, delegation, list comprehension, etc. and all of these are incredibly powerful. However, making your application only work by passing function pointers around confuses the hell out of some great developers let alone the ones that are likely to maintain the code! Be kind to others. If you’re not you’ll likely be sitting on tacks tomorrow.

How would you like to wake up tomorrow and be called “a_32″? Ok, then you’re weird. I’d be a bit unhappy. I’m also unhappy when I see code riddled with that. How long does it take to type arrayList32? Honestly. I hate the numbering and all that too, but that’s just irritation. Make your names a bit more descriptive. Nobody is going to be able to take a codeset riddled with alphabet soup and make sense of it. if it’s a Hashtable of Sessions, use something like “session_table”, or something similar.

We all have to get better with these things. I know I do. But, think about the people that are going to be fixing the problems you create today and remember that they likely know where you live at least 8 hours of the day.

Let us cover some of the basics. What I’m not talking about here is backing up your mp3’s or movies. Also, I’m not talking about making duplicates of your image files. There is no point to it unless you modify those files frequently. I’m talking about things like, your budget files, check books, documents, and anything that you customize on a fairly regular basis.

Personally, I have my .emacs file in a location that can be accessed at all times. But, I have it versioned so that when I make a change to that file I can deploy it on any machine that I have emacs on with a quick “bzr merge”. It’s great. Also, I can version my Gnome config to make sure that my menu items are available all over.

Now, more _critically_. What do you do when you have customized a user interface and those settings are stored in a file on your local system? For instance, “Program Files/World of Warcraft/WTF/Config.wtf”.  This file can change very frequently, sometimes on purpose. Versioning this file means that I can try all sorts of settings out and should something make the view disappear, I can revert back to a stable version. Not to mention, I can keep my settings the same across machines.

Now, I know what you’re thinking. Why in the world does it make sense to do it if all I’m doing is browsing the web? First, I’d question why you even have a computer, get an iPhone. Second, If you have done anything to customize your browser or bookmark information, that all must be stored somewhere. This is all information that you can version.

Keep in mind that while I did mention that I wasn’t talking about backups, it is important to back your _shit_ up. If you don’t, you’re bound to lose a lot, this is coming from someone who lost over 80GB of music collected over about 10 years. It is important, you should do it. Versioning your information will help with recovery, but is not the end all solution.

If you’re on board with versioning then you’ll need a strategy. Here is the approach I take.

• Get a secondary hard drive. This can be a full server or just an external SATA drive. Format it up, and we’re good to go.
• To back stuff up, you can just start dumping information on there.
• To version things, you need to do a few things.
• You need to pick a versioning tool that works for you. There are a large number of them out there. I prefer bzr, but it does not have a graphical interface. That may be a killer for some. If you would like a UI, I recommend subversion with TortoiseSVN or VersionsApp. There are plenty of tutorials online on how to use these tools, so I’m not going to cover that.
• You need to setup a repository on the secondary hard drive. This could mean just creating one on the directory or going into the server and doing it. But, you want to have it on a location that is not directly on your system. This ensures the redundency of your information should you ever need it outside of a system crash/failure.
• Once you have the repository, you are good to go. Start adding and removing and checking in and out.

I hope this has been informative and/or helpful to some of you. If anyone is interested I could do some deeper writeups on how to use the tools I mentioned. I just don’t feel like regurgitating Google. Feel free to post any questions you have.

Why do I bring this up? I’m trying say that I had an incredibly inflated vision of my worth to a company. This isn’t to say that it was necessarily innaccurate, although it was it’s irrelevant. All that I am saying is that my personal valuation of what I could provide to a company was fairly high. But, what I didn’t realize how little I was actually bringing.

Think about it this way. A company spends a great deal of time, effort, and resources in both people and materials to hire you, bring you up to speed, and then keep you happy over your time with that company. This isn’t a simple equation, but keeping it basic it looks like this:

recruiting + resources + salary = x

‘x’ is the monetary value that you are supposed to be worth to the company. That’s right, asset value. As with most things in accounting that hold a value, they depreciate unless more money is put into them each year. This is not giving you a raise or doing a review. Instead, this appreciation only comes from you, as an employee, getting better. This could be conferences, books, feeds, or even sitting in on a code review. Otherwise, your value to the company goes down each year.

That is called depreciation. When you purchase/build a house, the value doesn’t stay the same. You need to invest more to get more. This means time and money. If you can keep yourself on top of what is going on in the world within your field and be able to handle many situations, you’re keeping yourself classified as an appreciating asset.

I say all of this because it has helped me over the years to realize my actual worth to a company rather than my inflated view. If I never evolved or got any better, then I would still be where I started, which is casting lines into the stream. In fact, I’d be worse than that, because I’d have depreciated.

Search is a hard problem. It’s more than just saying, “This document uses the term Google. When someone searches for Google, I’m going to return this as a result.” Sure that’s part of the puzzle, but it doesn’t involve semantics. Google and others have been focused on web semantics for a long time. But, that doesn’t do anything for native language processing, sentiment, video translation, audio translation, and so on.

The strange thing is that humans don’t work this way. The human brain functions through relevance. So, if someone shows me a piece of paper with the solar system and the planets. And then I see a television show about the asteroid belt between Mars and Jupiter, I can infer a lot of things. Why don’t our technologies?

It seems that we are all afraid to move relevancy into it’s next stages. We have the technology to do it, but nobody is challenging the giants. I think that Michael Arrington got it right and that Tim O’Reilly missed the sentiment a bit. There needs to be competition. But for someone to focus on just an area where “Google isn’t” is not powerful. Look at Summize- Twitter, bought Summize and now has a worthwhile search tool for the Tweetspace as Tim O’Reilly calls it. But, that means nothing in terms of the potential they could have had. If they worked to get into FriendFeed, Plaxo, etc. they would have been the search tool for all of the social networks. This makes them far more powerful as a product, and company. This is what I see happening with Power Set and Tiny Eye. They are too focused on the problem they are trying to solve.

I think that search is the point. Search can bring our seemingly separated applications together. Search makes my blog, your blog, and everyone’s blog relevant. It enables me to write something here and within hours, have it be related to something that a few other people are talking about. So, search is the problem!

What I’d like to see is a search tool to come out with semantic search across all mediums. With Web2.0 and RIA’s on the rise…we need relatable and relevant information that isn’t stuck within the constructs of the conventional internet. This is when search will be 90% solved.

The Wheel?!? Oh my.

So you’ve decided that you need to use someones library. You’ve been searching and found many around. Great. That means you don’t have to spend the time to develop the solution yourself. In this case, you’ll want to pick the right tool for the job. But, how do you distinguish which is better? You may be thiking, easy, just pick and go. But, if you’re building a product, this decision can be crucial. It can affect many peoples time. So, again, how do you pick the right tool. While each situation has different dependencies, here are some of the things I use to decide.

What is the barrier of entry? In many cases I’m not going to be the last person to touch a piece of code. And, on top of that, the next person to touch it will be in maintenance/bug fix mode. So, I want something that is easy for someone else to jump into. This mostly means API. While there are a few other pieces to this that I’ll explain later, API is what you will use inside your code. Thus, someone coming into your code should be able to make sense of it without having to ask you all the time. So, the library should be easy to learn.

What is the community like? This is a very big factor in the decision because, like above, if the code is not easy to understand or if I suspect that there are issues with the library, I have the ability to find out when the community is large. This doesn’t mean that small communities are not helpful, look at the Axiom Stack…Small for now, but staying active on the forums. Is there some excitement? Is anyone talking about the library/tool?

Are you trying to sandblast a cracker? Every engineer goes through the phase where s/he architects for the moon. This is a bad thing. Using Dojo or ExtJS to alert some information to a webpage is sandblasting a cracker. Getting a backhoe to pick up dogcrap is sandblasting a cracker. Building a $4000 machine to play Pong is sandblasting a cracker. The point is, don’t overdo it. Pick something that is going to work for your problem, but that wont hinder performance, decrease everyone’s productivity, and cost a lot in the long run. You want the gains to be greater than the cost.

What is the quality of literature available? One thing I’ve noticed on the Django site is that the documentation is phenomenal. Not only do they have a 20+ chapter book detailing A-Z on Django, but they have their API documentation as well. While the API docs could use some sprucing, the information available is incredible. This is the same for ExtJS. The documentation is very thought out and appears as though it was a focal point in the development process. To add onto this, are there any hard-copy books available. Java has numerous books available. This makes it easier to find quick answers or to learn something from the “experts”.

What are we, neanderthals?

This is the time when you’ve searched. You find nothing. Not a single result on Google. You check to make sure you didn’t fat finger the search query, and still nothing. Well, it’s time to break out the red bull and prepare for that all night-er right?

Stop! It’s hammer time. First, before you start writing any code, rethink your problem. A lot of times you’ll create problems that don’t exist. By this I mean, you’re attempting to solve an issue that isn’t there. Another common situation is that you forget about the overall picture because you’ve been staring at the same problem for 15 hours straight. Take a break and come back to it. It may be that the problem you thought you had is a bit different or that there is a slightly different way of thinking about it. By removing yourself you allow your subconscious to process it a bit before returning.

Use your brick wall. In almost every programmers toolkit exists a brick wall. This is not for slamming his/her head against it. Instead it’s a person that s/he trusts to bounce ideas off of. Quite a lot of things make sense in my head…it’s unfortunate that those things don’t always pan out in reality. Thus, the brick wall. If I can bounce my ideas around a bit I’ll come to a better solution. Even if the person I’m talking to doesn’t say a word about what I’m talking about.

Buckle up. If you’re confident that you’re problem exists then it’s time to hit it head on. In the words of Rands, start! If you wait around trying to contemplate the issue, you’re just wasting time. You’re confident that you have an issue without a solution, so dive in and start hacking away. Use some common sense when you are solving this problem. If you suspect that the problem may need to be solved again then start making your own library so that others can use it.

I always find that taking a second to think about my problem and then bouncing it off the brick wall helps whether there are tools or not. But, I really find that the community can make or break my use of a library. The collective minds of others is a great thing to have.

I was hacking on some code and thought, it would be great if when I commit and pushed my changes back to the main branch, that it also updated the branch with the latest changes.

Enter “bzr-push-and-update“.

To get the tool working, I branched the copy from Launchpad, renamed the directory, and put it into my <python_location>/site-packages/bzrlib/plugins directory and it worked. No hitches or anything.

It’s great when awesome tools can be easily enhanced.

Maybe it is that we compete daily for survival in the world. Companies go head to head in an attempt to stay in business. Obviously I’ve over-dramatized it, but beyond this is there any competition setup similarly?

The reason I ask this question is because competition is healthy. What if we had an IT Olympics? What would it involve? Black hat vs. white hat, windows vs. linux, etc.? I’m just trying to entertain the idea.

What do you think?

Unfortunately, or fortunately, I have these kind of ideas every now and again. It leads to some entertaining day dreaming. When I snap to I begin thinking about how I could create that which I’ve daydramed about. It often leads to half attempted portions of an application. By the time I’ve finished hacking I have a subset of the functionality I imagined would work. This is the nature of the prototype; see a post I wrote earlier this year on prototyping.

Now, the constant Attention Deficit that I have due to my self-diagnosed N.A.D.D. means that as soon as my next big idea comes along I drop what I’m working on to persue that. This doesn’t work very well. It leads to a handful of half hearted attempts to produce anything worthwhile. Here are a few tricks that I use to make my day go more smoothly.

Break the monotony: In order to harness my ideas I tend to need to be fully engrossed in the concept. If I don’t have full confidence in what I’m doing then I lack the focus and attention required to be 110%. So, the way I combat this is by taking breaks. If I’m not fully into what I’m doing I give myself 5-15 minute breaks every 2 hours or so. This lets me recharge my focus by switching gears quickly over a short interval. Sometimes I’ll get up and walk around the office and chat quickly with someone about a random topic. But, it gets my mind moving in another direction such that when I return to my desk, I’m refocused.

Solve a problem: I try to solve problems. What I mean by this is not that I’m a problem evangelist, but instead that I work on the problems at hand rather than just trying to architect like crazy. I rather like not being an astronaut and prefer to stay that way. Plus, I tend to be far more interested in challenges, and problems present challenges.

Calling all units: When you code in pairs you have the interest levels of others to feed from. If you and another person or two other people are working together to solve a problem then you’re one step head of the game. I like to bounce ideas off others even if only for the brick-wall effect, it helps me to think through issues. When I grab another person to code with we usually end up being very productive pushing each other forward.

These couple of things help me to be as productive as possible. I try to use these techniques often as tools, just like my editor, in the sense that they can help me to be as effective as possible. When I’m done, I have a number of full featured prototypes that can be equally evaluated. This makes it easier for me or anyone to assess whether the idea really is something that can takeover the world…mwahaha.

The Example

Lets assume for a minute that you are the star programmer. As such you are a wanted person. The team developing Flaglets wants your time and effort to write a backend API that allows access to the database and that the team developing Rewquicks needs you to write an AJAX toolkit that supports loading of everything in under 3 seconds from request to finish.

You know you can do this work. Hell, for you it’s easy! So you throw on some tunes, and start pounding away. In the sprint you have managed to finish both tasks plus some. Again, you have reasserted your position as company superstar. All is good in the land of you and you move on to your next set of tasks.

The Maintainer

The product has been working for some time but a client found an issue with the way the Flaglets API is working. The data seems to be coming back mangled. You can’t work on the bug as you are fully allocated to all the current projects at the company.

Insert The Maintainer. This individual will have to run through your code and fix your bug. Oh and did I mention this is a P1? Well it is. Now s/he has to trudge through code to figure out what the internals mean. Leaving aside any inherent problems with the code itself…how am I to start working with this code?

The Maintainer can ask questions but that generally doesn’t provide enough context to get rolling. That then means that s/he is left to either return to the developer with more questions, which is not always possible, or fight with the code. The latter is usually the case.

You as the Developer

So, you are still that amazing developer. You are a code ninja, but you’ve been away from this code for quite some time. It starts to eminate a distinct odor; the scent of “code stink“. You start thinking that it’s about time you reworked parts of your code. But you start to run through that wretched smell and although you are and were the awesome superstar…you got better. You have realized that you really did not know what you were doing when you wrote that piece of code.

I bring this up because it’s important. Your code will develop this stink. If it doesn’t, you should be concerned for your job as you are likely on your way out. ;D

Anyway, the point is that you have to figure out what you meant when you created this piece of junk so that you can make it better. This now puts you into the same situation as The Maintainer.

Why It’s Important

Your documentation may help save the day. Not only will it save time and effort, but it will save a few hairs from quickly turning gray! Think of the hairs! When you document your code you are preparing any future readers for whatever it is that your code does. The main reason that documentation is so important is that it can help prevent bugs!

There have been many occasions where a decision was made to implement something a certain way because of a limitation or something else. Without commentary, anyone looking at that code without context might think to refactor it, but that could be detrimental to the functioning of the code.

Also, I am in a position where I review a good deal of code for quality so that we are doing things efficiently and effectively. I often have to ask what the purpose of some code is when a little notation would go a long way and save me from having to ask.

Digest in Moderation

Now, if you do no documenation, then get to it, but keep this in mind. As with anything, moderation is going to be your friend. Putting useless or obscur comments in your code can actually harm your effort. Find the balance. If something is not obvious by the code or you are unsure as to whether to comment, write a comment. Err on the side of caution. But, in all of this you need to make sure that you are writing useful documentation. Making a note about something that happens 15 lines down is fairly useless, but stating that the parameters should be a value of type X and will throw an exception otherwise is great.

Happy documenting!