Rajani’s weblog

It seems to me getting good at writing comments is an under-appreciated part of a Programmer's development. However, I feel that this is a part of programming that's almost as important as writing code itself. So, here are some of the biggest misconception about comments:

Comments are free

This is an assumption that most of us make at one time or another. Comments aren't actually executable code, therefore they aren't maintenance costs, right? As it turns out, this isn't true. When you update the code that the comment references, you usually have to update the comment as well.

Unfortunately, this myth is actually true most of the time. After enough time staring at a comment, it typically becomes "noise" that you tune out. Thus, comments have a nasty habit of not being up-to-date.

Comments make code more readable

This is by far the most pervasive myth that I've encountered. If anything, comments make code less readable. Nine times out of ten, I ignore comments unless I'm stumped. In fact, I'm tempted to make emacs hide all comments unless I explicitly expand them.

Comments don't make code more readable. They are ways to compensate for code not being readable.

You should comment every function, method, class, and module

How many times have you seen docstrings like this?

view plaincopy to clipboardprint?

1.    
2. def get_x(self):   
3.  """   
4.  This method gets x.   
5.  """   

 
def get_x(self): 
 """ 
 This method gets x. 
 """ 

This is about as close to being a canonical "bad comment", and yet people who should know better still do it. Why? Because they feel that they should document every function or class. The reality is that documenting something that needs no documentation is universally a bad idea.

Code must always be "self documenting"

Most of the myths thus far have been of the "comments are a wholesome, healthy thing variety". Don't take this to mean that I feel that comments are bad. The reality of the situation is that the decision of whether to comment is just like most other decisions in programming: it's about tradeoffs.

In most cases, comments should be viewed as code smells. But remember that code smells aren't necessarily bad. They're just hints that something might be bad. And sometimes, removing one code smell adds another one which may or may not be worse.

For instance, would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments? In most cases, code's readability suffers more when it's overly verbose than when it has a high comment to code ratio. Thus, I would choose to write the comment in most cases.

Using Google Public DNS

Configuring your network settings to use Google Public DNS

When you use Google Public DNS, you are changing your DNS "switchboard" operator from your ISP to Google Public DNS.

In most cases, the IP addresses used by your ISP's domain name servers are automatically set by your ISP via the Dynamic Host Configuration Protocol (DHCP). To use Google Public DNS, you need to explicitly change the DNS settings in your operating system or device to use the Google Public DNS IP addresses. The procedure for changing your DNS settings varies according to operating system and version (Windows, Mac or Linux) or the device (computer, phone, or router). We give general procedures here that might not apply for your OS or device; please consult your vendor documentation for authoritative information.

Note: We recommend that only users who are proficient with configuring operating system settings make these changes.

Important: Before you start

Before you change your DNS settings to use Google Public DNS, be sure to write down the current server addresses or settings on a piece of paper. It is very important that you keep these numbers for backup purposes, in case you need to revert to them at any time.

After changing your settings, if you encounter a problem and cannot connect to the Internet, please call our support numbers for troubleshooting instructions.

We also recommend that you download this page and print it, in the event that you encounter a problem and need to refer to these instructions.

Google Public DNS telephone support

• 877-590-4367 in the U.S.
• 770-200-1201 outside the U.S.

Google Public DNS IP addresses

The Google Public DNS IP addresses are as follows:

• 8.8.8.8
• 8.8.4.4

You can use either number as your primary or secondary DNS server. You can specify both numbers, but do not specify one number as both primary and secondary.

Changing your DNS servers settings

Because the instructions differ between different versions/releases of each operating system, we only give one version as an example. If you need specific instructions for your operating system/version, please consult your vendor's documentation. You may also find answers on our user group.

Many systems allow you to specify multiple DNS servers, to be contacted in a priority order. In the following instructions, we provide steps to specify only the Google Public DNS servers as the primary and secondary servers, to ensure that your setup will correctly use Google Public DNS in all cases.

Note: Depending on your network setup, you may need administrator/root privileges to change these settings.

Microsoft Windows

DNS settings are specified in the TCP/IP Properties window for the selected network connection. 

Example: Changing DNS server settings on Microsoft Windows Vista

1. Go the Control Panel.
2. Click Network and Internet, then Network and Sharing Center, then Manage network connections.
3. Select the connection for which you want to configure Google Public DNS. For example:
   • To change the settings for an Ethernet connection, right-click Local Area Connection, and click Properties.
   • To change the settings for a wireless connection, right-click Wireless Network Connection, and click Properties.
   If you are prompted for an administrator password or confirmation, type the password or provide confirmation.
4. Select the Networking tab. Under This connection uses the following items, click Internet Protocol Version 4 (TCP/IPv4), and then click Properties.
5. Click Advanced and select the DNS tab. If there are any DNS server IP addresses listed there, write them down for future reference, and remove them from this window.
6. Click OK.
7. Select Use the following DNS server addresses. If there are any IP addresses listed in the Preferred DNS server or Alternate DNS server, write them down for future reference.
8. Replace those addresses with the IP addresses of the Google DNS servers: 8.8.8.8 and 8.8.4.4.
9. Restart the connection you selected in step 3.
10. Test that your setup is working correctly; see Testing your new settings below.
11. Repeat the procedure for additional network connections you want to change.

Mac OS X

DNS settings are specified in the Network window. 

Example: Changing DNS server settings on Mac OS 10.5

1. From the Apple menu, click System Preferences, then click Network. If you are prompted for an administrator password or confirmation, type the password or provide confirmation.
2. Select the connection for which you want to configure Google Public DNS. For example:
   • To change the settings for an Ethernet connection, select Built-In Ethernet, and click Advanced.
   • To change the settings for a wireless connection, select Airport, and click Advanced.
3. Select the DNS tab.
4. Click + to replace any listed addresses with, or add, the Google IP addresses at the top of the list: 8.8.8.8 and 8.8.4.4.
5. Click Apply and OK.
6. Test that your setup is working correctly; see Testing your new settings below.
7. Repeat the procedure for additional network connections you want to change.

Linux

In most modern Linux distributions, DNS settings are configured through Network Manager.

Example: Changing DNS server settings on Ubuntu

1. In the System menu, click Preferences, then click Network Connections.
2. Select the connection for which you want to configure Google Public DNS. For example:

• To change the settings for an Ethernet connection, select the Wired tab, then select your network interface in the list. It is usually called eth0.
• To change the settings for a wireless connection, select the Wireless tab, then select the appropriate wireless network.

Click Edit, and in the window that appears, select the IPv4 Settings tab.

If the selected method is Automatic (DHCP), open the dropdown and select Automatic (DHCP) addresses only instead. If the method is set to something else, do not change it.

In the DNS servers field, enter the Google Public DNS IP addresses, separated by a space: 8.8.8.8  8.8.4.4

Click Apply to save the change. If you are prompted for a password or confirmation, type the password or provide confirmation.

Test that your setup is working correctly; see Testing your new settings below.

Repeat the procedure for additional network connections you want to change.

If your distribution doesn't use Network Manager, your DNS settings are specified in /etc/resolv.conf.

Example: Changing DNS server settings on a Debian server

1. Edit /etc/resolv.conf:

   sudo vi /etc/resolv.conf

2. If any nameserver lines appear, write down the IP addresses for future reference.
3. Replace the nameserver lines with, or add, the following lines:

   nameserver 8.8.8.8
   nameserver 8.8.4.4

4. Save and exit.
5. Restart any Internet clients you are using.
6. Test that your setup is working correctly; see Testing your new settings below.

Additionally, if you are using DHCP client software that overwrites the settings in /etc/resolv.conf, you will need to set up the client accordingly by editing the client's configuration file.

Example: Configuring DHCP client sofware on a Debian server

1. Back up /etc/resolv.conf:

   sudo cp /etc/resolv.conf /etc/resolv.conf.auto

2. Edit /etc/dhcp3/dhclient.conf:

   sudo vi /etc/dhcp3/dhclient.conf

3. If there is a line containing domain-name-servers, write down the IP addresses for future reference.
4. Replace that line with, or add, the following line:

   prepend domain-name-servers 8.8.8.8, 8.8.4.4;

5. Save and exit.
6. Restart any Internet clients you are using.
7. Test that your setup is working correctly; see Testing your new settings below.

Routers

Every router uses a different user interface for configuring DNS server settings; we provide only a generic procedure below. For more information, please consult your router documentation.

Note: Some ISPs hard-code their DNS servers into the equipment they provide; if you are using such a device, you will not be able to configure it to use Google Public DNS. Instead, you can configure each of the computers connected to the router, as described above.

To change your settings on a router:

1. In your browser, enter the IP address to access the router's administration console. 
2. When prompted, enter the password to access network settings.
3. Find the screen in which DNS server settings are specified. 
4. If there are IP addresses specified in the fields for the primary and seconday DNS servers, write them down for future reference.
5. Replace those addresses with Google IP addresses: 8.8.8.8 and 8.8.4.4.
6. Save and exit.
7. Restart your browser.
8. Test that your setup is working correctly; see Testing your new settings below.

Mobile or other devices

DNS servers are typically specified under advanced wi-fi settings. However, as every mobile device uses a different user interface for configuring DNS server settings, we provide only a generic procedure below. For more information, please consult your mobile provider's documentation.

To change your settings on a mobile device:

1. Go to the screen in which wi-fi settings are specified. 
2. Find the screen in which DNS server settings are specified. 
3. If there are IP addresses specified in the fields for the primary and seconday DNS servers, write them down for future reference.
4. Replace those addresses with Google IP addresses: 8.8.8.8 and 8.8.4.4.
5. Save and exit.
6. Test that your setup is working correctly; see Testing your new settings below.

Testing your new settings

To test that the Google DNS resolver is working:

1. From your browser, type in a hostname, such as http://www.google.com. If it resolves correctly, bookmark the page, and try accessing the page from the bookmark. If both of these tests work, everything is working correctly. If not, go to step 2.
2. From your browser, type in a fixed IP address. You can use http://18.62.1.6/ (which points to the website http://eecs.mit.edu/) as the URL*. If this works correctly, bookmark the page, and try accessing the page from the bookmark. If these tests work (but step 1 fails), then there is a problem with your DNS configuration; check the steps above to make sure you have configured everything correctly. If these tests do not work, go to step 3.
3. Roll back the DNS changes you made and run the tests again. If the tests still do not work, then there is a problem with your network settings; contact your ISP or network administrator for assistance.

* Google thanks MIT for granting permission to use this URL for the purposes of testing web connectivity.

Switching back to your old DNS settings

If you had not previously configured any customized DNS servers, to switch back to your old settings, in the window in which you specified the Google IP addresses, select the option to enable obtaining DNS server addresses automatically, and/or delete the Google IP addresses. This will revert your settings to using your ISP's default servers. 

If you need to manually specify any addresses, use the procedures above to specify the old IP addresses.

If necessary, restart your system.

killall pulseaudio
sudo apt-get remove pulseaudio
sudo apt-get install esound esound-clients libao2
sudo rm /etc/X11/Xsession.d/70pulseaudio

July 21, 2009

Nobody Hates Software More Than Software Developers

A few months ago we bought a new digital camera, all the better to take pictures of our new spawned process. My wife, who was in charge of this purchase, dutifully unboxed the camera, installed the batteries, and began testing it out for the first time. Like so many electronic gadgets, it came bundled with a CD of software. So she innocently ejected the DVD tray, and dropped the CD in.

I happened to notice out of the corner of my eye that this was happening. At which point, I -- now, try to imagine this in exaggerated slow motion, for full effect -- screamed "noooooooooooo", and frantically launched myself across the room in a desperate attempt to keep that CD from launching and installing its payload of software. It worked, but I nearly took out a cat in the process.

There's nothing wrong with the software that comes bundled with a digital camera. Or is there?

1. It's probably unnecessary. Any modern operating system (and even Windows XP!) can see and automatically download pictures from a new digital camera. No extra software needed. But in a questionable attempt to add "value" and distinguish themselves from their many digital camera competitors, some executive at the camera company came up with a harebrained scheme to include software with a bunch of wacky, unique features that nobody else has.

2. Hardware companies don't generally do software well. Digital camera companies excel at building digital camera hardware. Software, if it exists at all, is an afterthought, a side effect, a checkbox on some marketing weasel's clipboard.

3. Software of unknown provenance is likely written by bad programmers. All other things being equal, the odds that new, random bit of software you're about to install will be pleasant, useful, and stress free are ... uh, low.

One of the (many) unfortunate side effects of choosing a career in software development is that, over time, you learn to hate software. I mean really hate it. With a passion. Take the angriest user you've ever met, multiply that by a thousand, and you still haven't come close to how we programmers feel about software. Nobody hates software more than software developers. Even now, writing about the stuff is making me physically angry.

Isn't that an odd attitude coming from people whose job it is to write software? How can we hate what we get paid to create every day?

David Parnas explained in an interview:

Q: What is the most often-overlooked risk in software engineering?

A: Incompetent programmers. There are estimates that the number of programmers needed in the U.S. exceeds 200,000. This is entirely misleading. It is not a quantity problem; we have a quality problem. One bad programmer can easily create two new jobs a year. Hiring more bad programmers will just increase our perceived need for them. If we had more good programmers, and could easily identify them, we would need fewer, not more.

How do I know, incontrovertibly, beyond the shadow of a doubt, that the world is full of incompetent programmers? Because I'm one of them!

We work at the sausage factory, so we know how this stuff is made. And it is not pretty. Most software is created by bad programmers like us (or worse!), which means that by definition, most software sucks. Let's refer to Scott Berkun's Why Software Sucks to nail down the definition:

When people say "this sucks" they mean one or more of the following:

• This doesn't do what I need
• I can't figure out how to do what I need
• This is unnecessarily frustrating and complex
• This breaks all the time
• It's so ugly I want to vomit just so I have something prettier to look at
• It doesn't map to my understanding of the universe
• I'm thinking about the tool, instead of my work

How many of those do you think would be true of the software on that CD bundled with the digital camera? I'm guessing all of them. That's why the best choice of software is often no software -- and barring that, as little software as you can possibly get away with, and even then, only from the most reputable and reliable sources.

I don't look forward to installing new software. On the contrary, I dread it.

Let me share a recurring nightmare I have with you. In this dream, I'm sitting down in front of a computer which boots up, running an operating system I've written. I then launch a web browser I've created from scratch, all by myself, and navigate to a website I've constructed. I click on the first link and the whole thing bluescreens. And the bluescreen itself bluescreens and begins to fold in on itself, collapsing into a massive explosion that destroys an entire city block.

That's the good version of the dream. In the other one, there's just … screaming. And darkness.

In short, I hate software -- most of all and especially my own -- because I know how hard it is to get it right. It may sound strange, but it's a natural and healthy attitude for a software developer. It's a bond, a rite of passage that you'll find all competent programmers share.

In fact, I think you can tell a competent software developer from an incompetent one with a single interview question:

What's the worst code you've seen recently?

If their answer isn't immediately and without any hesitation these two words:

My own.

Then you should end the interview immediately. Sorry, pal. You don't hate software enough yet. Maybe in a few more years. If you keep at it.