Pages

Commenting Is Not An Option

  • March 22, 2010 20:58

Commenting code is a part of development and engineering that is overlooked all too often. It might be that developers are simply under so much pressure that they feel there is no time for commenting. It might be viewed as a hassle. And, it is not something that is required for the code to compile and execute.

The compiler sees comments as optional, but that does not mean that developers should see them the same way.

Commenting is a vital, I would even go as far as to say critical, part of any software engineering effort. If you have been in the business for any length of time, you have undoubtedly come across code that is missing meaningful comments. You probably spent a significant amount of time trying to figure out not only what the code was doing, but what the original author was intending to do. Perhaps you have even experienced this with your own code!

Try to get in the habit of adding meaningful comments while you are coding, and do not consider the project finished until the comments are in place. Often, the comments in code are the most up-to-date documentation that a project will have. Requirements and technical specs may be out of date once the coding actually starts, and keeping documentation up to date which is separate from the code is a much more complex task than keeping comments up to date. If you use Java, take a look at the article How to Write Doc Comments for the Javadoc Tool. Look at the Java source and see how the comments are formatted. With a little practice, commenting will become second nature.

What if you do not use Java? That’s ok — every language has some way to leave comments, and the principles apply just the same.

Here are five ways to make commenting work for you:

1) Comment the method signature before you write any code inside the method. Then write the code implementing the described behavior.

2) Comment private methods and fields, not just public ones. You can then tell the javadoc tool to include private classes in the generated documentation. The resulting javadocs will be invaluable for anybody that needs to maintain the program in the future. You can easily generate two sets of documents if needed, one for public use and one for private, internal use.

3) Update comments when you modify the code. Comments that do not match what the code is doing are not helpful.

4) Take advantage of version control keyword expansion in your comments. For example, including the CVS keyword $Id$ in your comment will tell you who checked in the file last, the date, the RCS filename, and the revision number.

5) Let your IDE do the work. Modern IDE’s understand javadoc comment format, and can often generate the boilerplate of the comment for you, including @param, @return, and @throws tags. You just have to fill in the blanks.

What other ways do you make comments in code work for you? Feel free to leave a comment below, and tell us about it!

Old Media, Social Media, and Developers

  • March 5, 2010 07:00

I recently attended the Twitter developer meetup, and one of the subjects that came up quite often was the question of how to get “old” media companies to understand social media. A couple of days after the meeting, I read this article from 1995, where the author predicts that no online database can ever replace your daily newspaper, electronic books will never catch on, and e-commerce is a joke. The article actually made me laugh out loud, but the confluence of the article and the questions raised at the developer meeting made me think.

True, it was 1995, and the internet was nothing like we have today. But what the author of that article lacked was vision. What else happened in 1995? Sun launched Java. The Yahoo! domain was created. RealAudio gave us audio streaming over our dial-up connections. People who were willing to look for the potential of this new technology found it, and many of them made a lot of money along the way.

Fast forward to 2010. Everybody has a web site. Most companies understand that commerce over the Internet is a viable business model. But social media is something new. Many companies, including media companies, are still struggling to understand how to fit social networking into their business. They are lacking the vision to see how to make this new technology, this new avenue of interacting with customers, fit in to their old ways of thinking.

Part of the problem is that social media is about community, more than marketing, and this is a change of thinking that is difficult for old media to embrace. Community implies an openness that many companies are not comfortable with. But this is a shift that will need to be made to make social media work for a company. Social media companies can make a big difference here by providing education, helping management and marketing teams understand how to use social media to create communities around their brands.

Another problem is that developer resources are required, and these resources are often stretched thin. Social media companies can make a big difference here by building tools and providing documentation to assist in rapid integration of social network features into a companies’ existing workflow and systems. This will also create an environment where companies that specialize in social media integration to thrive.

It will be interesting to see how social media companies tackle this challenge, and it is something that we, as developers, should be thinking about.

Java Network Proxies

  • March 2, 2010 22:57

Have you ever spent hours lovingly coding your Next Great Program, only to discover that part of your audience cannot use it because they are behind a proxy server? If you are going to be using the network, it pays to plan ahead for this situation. Adding proxy capability to your program is not very difficult. Here’s a quick code snippet that does just that:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public static void enableProxy(String host, int port, final String username, final char[] password) {
    System.setProperty("http.proxyHost", host);
    System.setProperty("http.proxyPort", String.valueOf(port));

    if (username != null && !username.isEmpty()) {
        Authenticator.setDefault(new Authenticator() {

        @Override
        protected PasswordAuthentication getPasswordAuthentication() {
            return new PasswordAuthentication(username, password);
        }

        });
    }
}

Calling this method with a host and port will set up the system properties necessary for proxy access to work. If the username is not null, it will also set up a PasswordAuthentication object to perform authentication as needed. To disable the proxy, call this method:

1
2
3
4
public static void clearProxy() {
    System.clearProperty("http.proxyHost");
    System.clearProperty("http.proxyPort");
}

Now, all you have to do is provide a way for the user to enter the proxy settings, persist the settings, and call the enableProxy method. At application startup, you can read the settings from where you have stored them and enable the proxy.

Another option is to tell the JVM to use your system proxy settings. However, I have had problems with this detecting the system properties in some cases on some operating systems:

1
System.setProperty("java.net.useSystemProxies", "true");

Adding proxy support to your code is easy! Taking the time to add proxy support to your application will save you headaches later on down the road. Happy coding!