Writing code tends to be harder than it needs to, because there’s a constant need to please a bunch of other people who want to read and under­stand it. Sometimes, the person who writes the code needs to worry about being able to under­stand it several months later.

Conven­tional wisdom holds that the solution to the problem is documenting the code appro­pri­ately. Conven­tional wisdom is wrong. Reasons are manifold, and quite obvious once you start to think about it.

Documen­ta­tion is always out-of-date. It’s impos­sible to have anyone and everyone who updates code to update the comments and documen­ta­tion accurately. Sure, you could try, but to a large extent, this is simply beyond your control. Typically, this means you need to assume the documen­ta­tion is wrong and read the code in detail anyway, so you might as well simply start by reading the code.

Reading the code is the only way to figure out what it is doing. Documen­ta­tion only tells you what somebody thinks the code is doing. It is quite possible that they’re wrong, or only partially correct. Besides, it’s better to build up a model of what you think the code is supposed to do, than to be told what to expect.

Code is more concise. If the code is well-written and self-documented, it is gener­ally faster to read the code and under­stand what’s going on than to read the comments (which are, by defin­i­tion, more verbose than the code they attempt to explain). And if you can’t trust the programmer to write good code, you can’t trust the guy to write good documen­ta­tion either.

There are some situa­tions where documen­ta­tion is neces­sary, of course. Examples would be when you are attempting to explain the motiva­tions or struc­ture of your design at a larger scale, or if you want to explain what the code is not — why you decided to something one way and not the other.

If you’re running an SSH server on a machine exposed to the Big Bad Internet, it is best to disable password authen­ti­ca­tion. Public-key authen­ti­ca­tion is a far safer option. Here’s a typical snippet of my server logs that explains why:

Nov 20 10:24:01 [sshd] Invalid user backup from 203.239.105.2
Nov 20 10:24:03 [sshd] Invalid user info from 203.239.105.2
Nov 20 10:24:04 [sshd] Invalid user shop from 203.239.105.2
Nov 20 10:24:06 [sshd] Invalid user sales from 203.239.105.2
Nov 20 10:24:07 [sshd] Invalid user web from 203.239.105.2
Nov 20 10:24:09 [sshd] Invalid user www from 203.239.105.2
Nov 20 10:24:11 [sshd] Invalid user wwwrun from 203.239.105.2
Nov 20 10:24:12 [sshd] Invalid user adam from 203.239.105.2
Nov 20 10:24:14 [sshd] Invalid user stephen from 203.239.105.2
Nov 20 10:24:15 [sshd] Invalid user richard from 203.239.105.2
Nov 20 10:24:17 [sshd] Invalid user george from 203.239.105.2
Nov 20 10:24:19 [sshd] Invalid user michael from 203.239.105.2
Nov 20 10:24:20 [sshd] Invalid user john from 203.239.105.2
Nov 20 10:24:22 [sshd] Invalid user david from 203.239.105.2
Nov 20 10:24:23 [sshd] Invalid user paul from 203.239.105.2
Nov 20 10:24:27 [sshd] Invalid user angel from 203.239.105.2
Nov 20 10:24:30 [sshd] Invalid user pgsql from 203.239.105.2

If you install Linux for the first time and are greeted with an ugly set of fonts -

1. Make sure you install all the popular TrueType fonts (Microsoft’s common fonts are gener­ally avail­able via your distribution’s repositories).
2. Remember to enable anti-aliasing of fonts. Anti-aliasing can be turned on through the desktop-environment’s config­u­ra­tion, for example, KDE’s Control Center.
3. Set the hinting to ‘medium’ while enabling anti-aliasing of fonts.
4. Change the user-interface fonts to something that looks good, like Verdana, DejaVu or Calibri. Firefox also comes with an ugly set of default fonts, so you may also want to change those defaults too.

Now that this site is hosted on my own server, I wanted ensure that the server is up and running most of the time. Although five 9’s is not my avail­ability target, I needed some mecha­nism by which changes and updates that I made to the site were not reflected in the produc­tion website (can I call it that?) until the right time.

The solution is a simple one: run a devel­op­ment website in parallel, so that all changes can be tested on that first. Updating the primary website would be like flipping a switch. Here’s how I managed this:

1. Set up a new virtual host for the devel­op­ment site.
2. Set up a new database for the devel­op­ment site and populate it with existing records.
3. Update the WordPress config­u­ra­tion file to select a different database based on the current working directory.
4. Set up server authen­ti­ca­tion for the devel­op­ment website.
5. Write an init script to copy (rsync) all the files from the devel­op­ment site to the primary one. Exclude the authen­ti­ca­tion files like htpasswd, of course.
6. Set up a depen­dency on the new script in Apache, so that restarting the service also restarts Apache (this is useful at times).

It’s as simple as that!

Disclaimer: I skated for the first time in my life this week, for not more than an hour. Every­thing I say in this post is based on personal experi­ence, so use your own judgment before doing something silly and injuring yourself. The respon­si­bility is all yours.

The ‘quad’ roller skates are simply shoes with four wheels under­neath. You wear the shoes and, instead of walking, you skate (or fall).

They say practice makes perfect, which is certainly true to some extent. However, like any other sport, there is a technique to doing it right that is far more impor­tant. Here’s a break­down of what I discov­ered this week:

Bend your knees

This is true for almost any sport. Bending your knees automat­i­cally forces you into a crouching position, moving your weight ahead of your feet. This ensures that you don’t fall backward, which is painful and dangerous. The instinc­tive reaction to falling forward is to put one foot ahead and stop the fall, which is exactly what you need to do to start skating.

Gather momentum

The simplest and probably the only way to gather momentum is to put one foot ahead and put your weight on that single foot. You have your knees bent, right? The trick here is to apply pressure on the foot not directly straight ahead but towards the side. That is, you push your right foot forward and towards the right, and then your left foot forward and towards the left alter­nately. This provides some control over your motion.

Moving your feet

Don’t straighten up

…unless you know what you are doing. If you are moving slowly, it is alright to straighten up temporarily, but you need to bend your knees again before stepping again.

Don’t put you weight on both feet

Consider your normal walk: your front foot presses against the ground, while your back foot provides support. It’s the same principle at work here. Naturally, you can’t put pressure on both feet, other­wise your feet will drift wider and wider apart until you do the splits.

A possible misun­der­standing by the novice is to imagine that the wheels would magically carry him ahead. In reality, the best analogy to roller skating is walking, except that the ground is rolling away behind you. Ergo, you need to lift up one foot at a time and place it ahead.

P.S. — How often do you get to use the word “ergo” in your posts?

A useful paradigm that should be consid­ered when a stateful software system is to be designed is idempo­tence. Leaving aside its exact defin­i­tion in mathe­matics and computer science, idempo­tence can be roughly described as a system charac­ter­istic whereby, calling an opera­tion multiple times is equiv­a­lent to doing it exactly once.

For instance, setting the value of a variable X is an idempo­tent opera­tion, because setting its value to be Y several times has the same effect as setting it just once. On the other hand, incre­menting its value is not an idempo­tent method because the result depends on the number of times the opera­tion is called.

Imple­men­ta­tion

Before delving into why you might want to have idempo­tence, let’s have a look at how it can be imple­mented. One way of doing it is like this:

Design a state machine

A state machine identi­fies every unique state that the system can exist in, with a clear indica­tion of which states the system can transi­tion to from any given state, and under what conditions.

Design a minimal API

An appli­ca­tion program­ming inter­face is the gateway for external systems to interact with the service. We start by designing a minimal API, identi­fying all the methods that could change the state of the system. It is best not to clutter the API with non-critical methods at this stage.

Expressed differ­ently, an API method repre­sents a single transi­tion in the state diagram. For example, a system could have states such as Ready­ToP­ur­chase and TaxAdded. The addTax() method, if successful, provides the transi­tion from the first state to the second. This method can never be applied a second time, because by then the system has already moved on to the next state.

An impor­tant restric­tion on the API is that if the state has some attrib­utes, they must be maintained metic­u­lously and checked against incoming requests. Suppose the addTax() method takes a parameter called amount. If the method is called again with the same amount, then the expected response is success, since the system is indeed in a state that the function call was supposed to move it to. However, if amount is different, then the response should be a failure, or at least some kind of partial failure — other­wise, the client will assume that the new tax amount had been added. A state should never change its internal attrib­utes once they have been set.

Transi­tions should be atomic

It goes without saying that transi­tions need to be atomic, so that multiple requests do not corrupt the state while the system is transi­tioning. This can be achieved easily by acquiring a lock on a mutex at the start of a transi­tion, and releasing it on completion.

Why Idempo­tence?

Naturally, it is a good idea to ask why we are putting in so much effort. While this may seem inordi­nately complex at first, you will soon discover that such a design actually simpli­fies the system tremen­dously when there is a great deal of concur­rency. When there are a large number of processes or threads commu­ni­cating with each other and the number of messages exchanged is huge, idempo­tence provides a guarantee of sorts about what the system can or cannot do. The state machine approach allows you to simply worry about the system in its current state, rather than the system as a whole. As a debug­ging technique, the devel­oper simply needs to say, “This was the previous state A, and now it has moved into this new state B — what combi­na­tion of parame­ters caused such a transi­tion?” Idempo­tence makes this approach even more robust, ensuring that the system works in the face of message dupli­ca­tion and errors.

This robust­ness also allows the design to sacri­fice a reliable commu­ni­ca­tion layer in exchange for speed. For example, TCP (which has a larger overhead) can be replaced with UDP, since the appli­ca­tion is resilient to message loss and duplication.

This is the no-nonsense guide to creating your very own awesome beveled logo using GIMP, something that looks like the image shown here. There are detailed guides floating around in the series of tubes known as the Internet, but this is for those who are put off by tedious expla­na­tions and figures. Naturally, you need to be know the basics of GIMP if you want to under­stand this guide.

So here goes:

1. Create a new image slightly larger than the desired image size with a trans­parent background.
2. Make a rectan­gular selec­tion the size of the actual logo, convert it to a round-edged rectangle and fill the selec­tion with the highlight color (for example, the red on the edge of the logo).
3. Dupli­cate the layer twice.
4. Fill the lower­most layer with black, and blur it in order to create a shadow effect. It needs to spill out from behind the main logo slightly. Scale up the layer a few pixels if requried.
5. Scale down the top most layer by around 10 – 15 pixels, and apply a slightly darker shade gradient to it. (for example, a darker shade of red). The gradient should be subtle and slightly asymmet­rical. Blur this layer just a little, so that it merges with the middle layer which is just below it.
6. Create a new text or image layer to add your logo to the image foreground.
7. Save your file.

That’s it — you’re done!