Why I don’t write code comments

April 5th, 2009

These days I was configuring some personal projects on ohloh and one thing called my attention. Ohloh showed the message “very few source code comments” in all my projects.

This is no surprise to me. I really don’t like to write source code comments. Why? Because if my code isn’t clear and easy enough for one to read and easily understand, I need to refactor. Many times I ask friends to take a look at code snippets and check if they understand. When they don’t, the method is usually too big or the variable/method names are not clear enough, and then I refactor to make it better to understand.

One example that I love (and use in many presentations) is the code to send e-mails using Java Mail API. The code would be something like this (from Java World tutorial):

// create some properties and get the default Session
Properties props = new Properties();
props.put("mail.smtp.host", _smtpHost);
Session session = Session.getDefaultInstance(props, null);
 
// create a message
Address replyToList[] = { new InternetAddress(replyTo) };
Message newMessage = new MimeMessage(session);
if (_fromName != null)
    newMessage.setFrom(new InternetAddress(from,
        _fromName + " on behalf of " + replyTo));
else
    newMessage.setFrom(new InternetAddress(from));
    newMessage.setReplyTo(replyToList);
    newMessage.setRecipients(Message.RecipientType.BCC, 
            _toList);
    newMessage.setSubject(subject);
    newMessage.setSentDate(sentDate);
 
// send newMessage
Transport transport = session.getTransport(SMTP_MAIL);
transport.connect(_smtpHost, _user, _password);
transport.sendMessage(newMessage, _toList);

I know that this is just an example but you know that it’s not difficult to find monsters like this one in production code.

This code is so difficult to read that the programmer had to say what he was doing, otherwise nobody would understand its purpose. There is a lot of infrastructure and business code together resulting on a huge abstraction leak.

Now take a look at the following code (from Fluent Mail API) and tell me how many seconds do you need to understand what the code does:

new EmailMessage()
    .from("demo@guilhermechapiewski.com")
    .to("destination@address.com")
    .withSubject("Fluent Mail API")
    .withBody("Demo message")
    .send();

This is an extreme example, of course. Maybe you will not write Fluent Interfaces for every little thing you need in your code, but if you add just a little bit of organization (using a better abstraction) it will already improve code readability:

class Email {
    public Email(String from, String to, ...) { ... }
    public void setFrom(String from) { ... }
    public void setTo(String to) { ... }
    public void send() {
        // put your complicated Java Mail code here
    }
}

Just by encapsulating the code in an abstraction that makes sense the WTF effect will be sensibly reduced. The programmers can now at least assume that the code sends e-mail messages since it’s included in a class called “Email”.

And that’s the point. When I create a culture of prohibiting myself from writing code comments, I’m obligating me to write easy, maintainable and understandable code.

That’s very extreme, I know, but the results of this approach are awesome.

Open source: “I don’t use open sorce software because I want support”

April 1st, 2009

“I don’t use open sorce software because I want support. I want to pay for it, so I can have support if I need.” That’s what a lot of people say about free and open source software. But today I came to a really interesting situation that it’s interesting to share.

We were configuring a continuous integration server at my team for a new project and we decided to use Integrity – that is a very simple yet powerful and beautiful tool. Our goal was really really simple: run tests, deploy the application and run more (acceptance) tests. Then we came to a situation where the tests were not running and the reason was somewhat bizarre. Integrity was opening a subshell to execute our build (and that’s very fair), but the problem is that Python‘s sys.stdout was showing an Unicode error, because the test reports have a lot of accents. For some strange reason the very same code that was working in our shells was aborting with an Exception when executed in a subshell.

Given that complex situation, I decided to go to the website’s FAQ to see if somebody had this kind of problem before. I thought that maybe some configuration or environment variables setup could easily solve my problem. After some minutes of browsing I found instructions to configure Passenger user switching to overcome this problem, but I got no success.

Then, very frustrated, I decided to take a look in the documentation again and this time I saw a link to “support”, that pointed me to an IRC channel.

In five minutes I was talking to 2 commiters of the project and was having a high level discussion about the problem, the causes and the possible workarounds. The best part was that it took exactly 30 seconds for them to understand what I was talking about and they immediately started pointing me to solutions and asking me to try things… Thank to the guys’ tips (and Google) I could solve the problem in the end.

If you don’t like open source software because of the support, then I would like to ask you: in what reality do you live? Do you prefer to talk about “subshells” and “environment variables” with some call center attendant or do you want to talk to the people that can really help you solve your problem?

In other situation I was working at a company that used a VoIP telephony equipment that only worked on Windows. I wanted so much to use my preferred Linux distro, but that would mean that I couldn’t have a telephone. So, since we had a gold support plan (because we had a lot of PBXs with almost 200 branches), I decided to call the company and ask why they didn’t have a Linux version. I also tried to propose to or account manager: “we can implement that for you, just give us the Windows source code or protocol spec that we will implement everything for you and give you the source code and all the rights for free”. That was 6 years ago and they still don’t have a Linux version of the software….

Then I want to ask again: do you want to pray for your vendor to implement the solutions that are important to you or do you want to have the power to do it yourself when you need?

Think about these things. In the great majority of the times I asked for support in open source projects they were infinite times better than any paid support I’ve ever had!

Hello World!

March 31st, 2009

Although it’s a cliché, this is certainly the best title for a programmer’s first post! :)

After a long time of procrastination I’m finally starting my english blog! My intention is to continue the well succeeded work that I did in my portuguese blog, but this time opening the discussion and exposing my opinion to a bigger audience.

Hope that someone can find valuable information and insightful thoughts about software development, technology, agile methodologies and many other things that I will share here.

Hello world!