The Code Makes My Eyes Bleed

Not often do you stumble into projects that are pristine. I certainly haven’t anyway. Almost every project I’ve been involved with has required some degree of unfarking to bring it to a close. But, surely there are things that we can do to make it so that those who have to come in and “finish” don’t have the undying urge to gouge their eyes out with rusty spoons?

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.

Getting It Done “Write”

The software development industry has a problem. Most of us are lazy. In this cling to the “do as little as possible” attitudes, we lack the necessary desire to document what our code does. Granted, if you are anything like me and write “perfect” code then you shouldn’t need to document your code right? Wrong. Documentation is the sort of effort that proves fruitful later on in a couple of ways.

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!

The Next Holy War: Distributed VCS versus Centralized VCS

I often find myself being an advocate for something specific in the technology field. And, many times this relates to the common “holy wars” that most of us are familiar with. I sit on the emacs side of one, and the open source side of another. You can immediately understand what I’m referring to when I say “emacs”. The next topic for war I believe is going to come down to version control. If you want more proof, take a look at Derek Slager’s DVCS Myths post.
Currently there are two main types of version control and source management, centralized and distributed. I’ve used centralized systems for quite some time and although they have served a purpose…I find them to be outdated. Now, hear me out before getting frantic. The software industry is changing. We are in the midst of evolving the way we work. We want to work bigger, faster, better, stronger, right? There has been a push over the last 10-15 years to revamp our development methods. What I’m referring to here is the waterfall to agile approach of things.

The waterfall approach is about building very hard speced systems over the course of “x” to completion. Once the system is complete, you test, debug, etc. This is often very clunky, doesn’t describe the entire system, and takes an extremely long time to obtain any tangible assets. By this I mean that nobody can see a working system part of the way through. Thus, expectations are usually high leading let-downs as a result. The agile approach, in many ways, was created as a way to attack the problems at the core of the waterfall approach. Also, certain agile approaches can help do more such as improved development efficiency. With this in mind, and understanding that I sit on the agile side of that fence lets talk about source code management (SCM).

Centralized version control was fantastic. It provided the foundation for storing code in one place such that developers could work on code and then push it back into that one location. Not only was this able to happen, but we could lock, merge and tag. These are all good things by the way. What good would any SCM be without them. The lacking areas are the repository and the workflow.

Since we talked a bit about workflow above as it pertains to development, lets talk about how it relates to source management. In the likeness of the Pragmatic Programmers we know a few things to be good. That we want to refactor early and often. And, we do not ever want to settle with broken windows. These few things being said, lets discuss them as they pertain to workflow. In any SCM we can accomplish each, right? We checkout code, modify it, and commit new code. Centralized or decentralized. But, I’ve found it easier to manage the above “good things” within distributed version control system (DVCS). When I am working on refactoring code, I want to have an experimental branch. This allows me to create features, change API, and muck with the general internals of a codebase without destroying the greater good. That brings me to broken windows. If all developers commit to a central repository, then all code is based on said repository. Thus, if you have a team of n (including yourself), you can stop n-1 people from working for h number of hours in a day by commiting some code that you thought worked.

With a DVCS, you are commiting your code to a branch. This means that you are not commiting to the central repository. Sure you have to deliver your changes at some point, but you are more likely to have your code in working order. Also, it allows for easier testing of your code, since your code will be a subset of all new features and changes. So, when we refactor our code or write new features we are setting ourselves up better by having the DVCS.

Now that I’ve touched a bit on the workflow we can talk about the repository. Distributed version control systems are just that, distributed. The point is to make it easy for developers to make changes while being anywhere. The way this works is with distributed repositories. Distributed systems work by branching. Although the notion of branching is built into SVN and other centralized systems, they don’t work the same.

Distributed systems, as seen in the image, mean that everyone is a node, or using our terminology, a repository. Rather than just feeding off one main location, I can pull from my friends repository, push code changes up there or to a different repository. Branching allows for this sort of behavior.

So, when I modify code on my system and then commit it to my local repository, I can push those changes along to whomever or they can pull them down from me, and everyone has my latest changes.

So, I believe the thought going through your mind at this point is, wait…You’re contradicting yourself. If I want to commit often and refactor even more often then I’ll likely break something. Thats not good. The point here is that you shouldn’t work directly in your local repository. You should branch the repository and do work within the branch. For instance, say you are working on an OS. You can have a branch for networking. I can then grab that branch but if I have to implement some experimental IPV6 functionality, I’m not going to do so such that everyone gets those changes. I’ll branch the code base and do it there rather than expose that code to everyone. With a centralized system, you can branch the code…but merging the modifications back would be complicated and cumbersome, and in some cases not possible. If you need more proof take a look at Griddle Noise: What a DVCS gives me.
This being said, the industry uses centralized version control for most work currently. I feel that the change to agile programming should be accompanied by a SCM system that easily supports agile processes. A DVCS goes hand in hand with a distributed source management system.

There, I’ve stated my thoughts on the point. Flame away.

Useful Emacs Modes

M-x flex

One thing to keep in mind is that while I use and love emacs, I think it’s important to have an editor you like and are comfortable with. Whichever is up to you. I have heard many-a-thing about many-an-editor and I don’t care to be a missionary for emacs so what I will say this; use an editor that you are comfortable with, but that is powerful. One that allows you to modify the text on your screen in a few simple keystrokes. The two main ones that come to mind here are emacs and vi(m). But, if you can make Notepad++ or others do this, then enjoy. You will never know everything there is to know about your editor, however you can strive to become a more efficient user. When I made the switch from TextPad to emacs I cut down my coding time by probably 20%. Thats huge in the grand scheme of things. If you think about the number of hours I work, and take 20% of that, you’ve freed a huge chunk of time I can be focusing on other things like YouTube and Facebook. The productivity gains are wonderful. ;D

Since I’m an emacs guy I’ll talk about a few of the modes that I am really keen on and how they help me or _will_ help me based on my experience with other modes.

js2-mode

As you saw with my post about the Axiom Stack, I tend to do some JS development. I’ve made due with some JS modes and tried to find something that I liked but this one seems to take the cake. One thing that has irked me about other JS modes for a while is their lack of understanding of the regexp. When I throw a regexp in there and use something to the effect of str.replace(/\’/g, ”) the mode blows up and I then lose all syntax highlighting for the rest of the buffer. js2-mode fixes this. *WOOT*

Yagge wrote this mode as a direct port of the Rhino code. That means that there is full JS support up to JS 1.7. Can you say list comprehension? I CAN and js2-mode can see it…therefore so can you! Eventually his hopes are to turn this into something that can function much like IntelliJ or Eclipse. As a start, he’s really gone beyond what I expected when my friend at zen-hacking.com pointed this out to me.

The indentation is a bit wonky but true indentation is a complicated feature to include. There are a number of things that people “prefer” making indentation a very difficult task. However, I can only see this feature getting better with time.

I’ve been using it since it came out and am very impressed. Just starting out it surpasses the other JS modes out there. I recommend giving it a try.

You can find this mode at: http://code.google.com/p/js2-mode/

yasnippet

Today, my friend at zen-hacking.com stumbled upon a mode called yasnippet. This is a snippet mode if you couldn’t guess it from the name. What does this mean? You can stop having to write boilerplate code. Instead, you type something as simple as “class”, then tab, and the boilerplate appears before you. This mode adds another feature that is found in editors like eclipse. Also, it’s scalable. As it stands, there are a number of modes already handled such as cc-mode, python-mode, and ruby-mode. But, should you write a language for your day-to-day operations, you too can build snippets of boilerplate. Check out this video: http://www.youtube.com/watch?v=vOj7btx3ATg

You can find this mode at: http://code.google.com/p/yasnippet/

hippie-expand

This mode is a very useful mode for helping you code faster. How so? Hippie-expand records the things you’ve previously typed and, with a command, will expand whatever you are typing into what it matches. This is extremely handy as it cuts down on the amount that you must recall at the time of typing and it cuts down on the sheer amount of typing that one must do.

I think the obvious point here is that with this mode you become more productive. You can focus more on the algorithm or problem at hand and in coming up with a solid solution, rather than having to focus on remember what that farkin’ variable name was. You can just type the start of the word and then whatever key command it is and you are scrolling through your set of variable names.

You can find this mode at: http://www.emacswiki.org/cgi-bin/wiki/HippieExpand

Fin

No, this isn’t a mode. These are three of the modes that I use that I find to be extremely helpful. What modes do you use? Two that I would like to get working better are Remote File Editing (tramp-mode) and Version Control (vc).

RantOn: External Services and API

/rant on

While taking a break from the work effort I thought it may be cool to write a tiny module that was pluggable for my blog and possibly other services. I’m a huge fan of iLike. I love music and listen to it all the time. However, there are never enough hours in the day to find new artists and new music. Pandora is a great tool for this too but it’s not socially generated. This is where iLike has hit the nail on the head. Where they fail however is opening their API.

I am of the opinion that if you are gathering information for social networking purposes that you should allow developers to extend that functionality. I felt like creating a fast little php template that pulled information in from their site that I had full control over. Generally not too much to ask. LibraryThing, del.icio.us, and others do it so I assumed that iLike would do the same. However, it appears that they are more geared towards having their own marketing than letting anyone create what they want. They have a flash widget that they allow you to put on your site, but what about those people that want to customize the look and functionality? This widget is very limiting.

The problem I have with this and any other service that leaves out the open API is that they are really restricting the developer community from making awesome applications utilizing their services. I tend to like to customize the look & feel and functionality of tools and sites that I create. Why cant it be the same with services like that. It’s really not complicated to make rpc/soap available to the community, so why not do it?

My plea to all of you creating new applications. Make time and some effort for services. Provide some external API that developers can plug into and use. It will not only help them, but it will help you too. Be kind to the community. Give back, give us an API.
/rant off

12 hours is costly…but sleep, so refreshing.

So, just before I went to sleep Sunday night I had managed to get a number of things working. This was great news. I had content loading to the screen: textures, models, and custom shaders. I had managed to set up a few functional pieces as well: skymap, lighting (through shaders), and a camera system. All of this was done with the XNA 2.0 framework.

However, _just_ before I went to sleep I managed to break something such that the engine would crash at runtime…debugging this seemed to be of no help, and since this was after about 12 hours of coding, I decided the best thing would be sleep.

Last night I returned to battle this phantom crash. Turns out, which I found in a matter of minutes, when you have a class, static, named “Content” that you are using to set the root of the content repository, you shouldn’t name a variable - “Content”. Yes, yes…now is the time to /slap and /punch me. It was at the end of 12 hour coding stint…thats all I got.

Well, to bounce back from my folly and I was able to implement a pretty basic Octree system with correct culling and so forth. I may try to grab some screenshots tonight for you as this is a bit more impressive than “WOOT! I HAVE A SQUARE!”. However, I may just continue to press forward with the engine development and see if implementing an RTree is worthwhile. Thoughts?
That is all you get for now.

Back to Dev.

So, I’ve started getting back into development, outside of work. It’s great. I was having issues with my desk that caused me to not want to code with it…then it broke and made things all better!
The biggest thing I’ve been doing lately is actually working on my 3D engine. However, rather than rewriting the JoGL code that I once had, I thought I’d give the XNA2.0 framework a try. One word, “wow”. It’s pretty sweet. I’ve been able to push beyond what my older engine could do and now I’m able to load models and even use shaders.

I’m extremely impressed with how they’ve got it setup. I’ll be posting demo screen shots later this week that will include lighting details and other specs.

Undertaking Projects

So I read a post from a friends blog, “Working Small”, and after I read the quote from Linus Torvalds in it I decided it was time to argue points.
Well, the next day at work we talked about the quote because I was curious about perspective on it and it seemed that we both agreed. What we both took the quote to mean was that looking at a project can be a very daunting task. Taking it from start to finish while meeting requirements, fixing bugs, working with new technologies, etc. is quite complicated. However, what we concluded is that the quote really depicts a view on how to go about working on these kinds of projects.

First you must understand that projects for clients are going to need to be thought out, put into a timeline, and then worked on until completion. However, what concerns me is the working on until completion part…thats the portion I do. If you start out by taking some project and work on it’s entire architecture and _then_ begin to develop it, you may have problems.

One of the problems, and possibly the worst, IMO, is the lack of agility. You will have a much more complicated time restructuring a system if you go through the architecture in advance of any of the development. Instead, if you focus on smaller tasks you will have a better idea of the start and end points and be able to develop with a clear vision in mind. Also, you have more ability the change an API or develop new ones as you are developing it due to certain needs. You are less likely to be able to change due to clients needs. Many projects go for some period of time and due to this, requirements may change. The client may decide over that period of time that the functionality of requirement ‘x’ actually needs to do ‘y’. In a hard fast architecture you have 0 agility. Instead, you need to add more to the application which creates bloat and functionality that may not be used. This leads to the inability to refactor your code effectively without leaving broken windows.

Now, these ideas are not new. The guys over at the Pragmatic Programmer have been talking about it for some time, however, I thought that the quote was the common link between what those guys are saying. It really embodies the view most developers should have when undertaking a project. While some architecture is important, it should not be the entire focus of the initial stages of development. There is something to be said about building prototypes and hashing ideas out before really designing the architecture of the final product.

You must have some idea of where you want to go, but that does not mean you should throw agility and prototypes out of the window.

Effective API Design

When I sit down to write an application I usually try to come up with some prototype of how I think the code base should be designed. Many times this prototype is off in one way or another, but it allows me the ability to modify the functionality easily. Prototyping the API allows me to better design the architecture. Once I’ve decided on the architecture and API I can then have other people implement additional functionality atop the API I’ve created. However, once I’ve exposed this API it becomes increasingly more complicated to refactor naming and functionality of the API.

The other day I was searching for some Java related information and found a lecture given by the author of the book Effective Java, Joshua Bloch. I listened to the whole talk and read through his slides and he really hit the nail on the head. He makes references on how to design API, how to develop methods, how to decide on parameters, etc. He even comments on effective documentation, a major side of dev. that developers choose to skip, including myself.
Video in Flash (about 1 hour 9 minutes) - http://www.infoq.com/presentations/effective-api-design
Slides in PDF - http://lcsd05.cs.tamu.edu/slides/keynote.pdf