Are Comments Evil?

I’m a bit late to this party, with the majority of the opinions on the subject having been weighed in last week and the week before it, but after reading Jesse Liberty’s Coding Without a Net post and then Davy Brion’s response to it, I’ve been noodling on my own usage of comments in code and what I think about them.

In the end, I think I have to side with Davy and answer the question of “are code comments evil?” with “it depends”. The biggest argument I’ve read against code comments is that they can easily go out of sync with the code. While I agree and have certainly seen it happen many times, I don’t think that’s a reason to avoid comments. I think that’s a reason to hire developers with better discipline. After all, when a comment is replaced with an extra lengthy and specific method name, who’s to say that some developer won’t come along at a later date and change the guts of the method without updating its name? It really is still the same problem — the developer wasn’t diligent enough.

Don’t get me wrong – I don’t think extensive comments are a viable alternative to good naming conventions or proper designs, but I still believe comments can be very valuable when expressing the motivation behind code being written a certain way (e.g. to work around a bug or to address some design considerations). Properly written comments that detail the “how” behind the “what” can save time that’d otherwise be spent looking up a wiki page or some other document that explained the design. And that’s assuming that there even is such a document.

Used in combination with good naming practices, these comments can make reading and understanding code a lot easier. Where this scheme is pretty much guaranteed to go pear-shaped is if the comments are required. For example, I’ve seen projects configured to fail to build if there is a non-private method that’s missing its XML documentation. The result is not unexpected — every public method is decorated with an auto-generated XML comment that is absolutely obvious and sometimes a bit weird – GhostDoc is pretty good at parsing method and property names into English sentences, but it’s not perfect and produces its share of “Validations the handler” on a method called “ValidationHandler”.

The worst kind of comment in my mind, though, is the “angry and lazy developer” comment. Have you ever come across a section of code where someone took the type to type in something along the lines of “This is horrible. Does this even work?”? If yes, then you know what I’m talking about. It’s when a developer came across some code and instead of figuring out what’s wrong with it and fixing it (thereby leaving the campsite cleaner than he found it, as it were) or asking the original developer, he instead chose to leave a passive-aggressive comment in the code and check it in. The odds of someone looking at that piece of code may be relatively low and the comment will survive days, then weeks, then months. It’s even more fun when an aforementioned undisciplined developer comes along and fixes the code without altering the passive-aggressive comment.

So in the end… “it depends”. As with many programming paradigms, there’s a lot of ways to misuse code comments, but I think there also are ways to use them for good rather than evil and that they should not be abandoned completely. The truth is in the middle, not in the “comment everything” or “comment nothing” extremes.

On Importance of Good Method Names and Paying Attention

I spent a somewhat frustrating hour at work today trying to plot a straight line on a chart using a framework that shall remain nameless. I quickly had the slope and the y-intercept worked out and all I needed were two x values to plug into the equation to calculate some points. I already had another series plotted on the same chart and just picking the minimum and maximum x values from it was sufficient for my causes.

Naturally, I could do the legwork of figuring the min and max myself, but why do the work when the framework can do it for you? I poked around and found a couple useful methods: FindMinValue() and FindMaxValue(). I had assumed (based on Intellisense and lack of code docs) that they would return the values I needed. Then a couple things taught me that wasn’t so at all:
1. I used var to declare my variables, so I didn’t notice that the functions in question are returning integers.
2. I was wrong in my original assumption. Those methods aren’t finding and returning the min and max values. Instead, they’re returning indices into the array of points in the series, pointing me to the location of the min and max values.

I guess technically the method names didn’t lie: they are “finding” the location of the values for me. I still found that to be counterintuitive. In my opinion, FindMinValueIndex() would’ve been better.

So, the lesson is: pay attention, don’t assume anything, and if you ever release an API framework, try to be as clear as possible about the intent of your methods when you name them.

Toronto Code Camp 2010: Lessons Learned

This weekend I had the great opportunity to attend Toronto Code Camp 2010. It was my first code camp and my first major dev-related event, so I was pretty excited all around. I’m happy to say it didn’t disappoint. Over the next few days I’ll post some of the notes I’ve made and/or links to slides if I can find them, but for this point I’d like to just list some of the lessons I learned.

In no particular order…

1. Having business cards on hand is important.

Every conversation I had in-between sessions ended with an exchange of business cards. The ones I had with me were employer-branded, which is better than nothing, but I think I will be making some of my own soon.

2. Talks that look irrelevant may turn out to be very enjoyable.

I’m primarily a desktop application developer just starting to poke my nose outside .NET 2.0. I was worried for a bit that the event was very focused on technologies I don’t work with. Well, lesson learned: that doesn’t matter. Learning something outside my normal work was perhaps one of the most valuable things I took home with me.

I would almost go as far as to say “go to talks on subjects you know nothing about”.

3. Bring food.

The code camp’s organizers, volunteers, and sponsors do an excellent job of bringing a free event out to the developer community and provide a free (!) lunch to the majority of the attendees. Alas, for a day full of thinking, it would be helpful to have some “brain food” on hand throughout the day.

I didn’t bring anything along this time and my afternoon sustenance was comprised of a Coke and a Bounty bar out of the vending machine. This is not a mistake I plan on repeating.

4. Even though they may work with different programming languages or technologies, all developers speak code.

I don’t think there’s anything else I need (or have to) say about this one. When in doubt, sketch out some code on a napkin. Maybe clarify the syntax. And suddenly you’ve explained a concept to someone even though you’re working in drastically different areas.

5. Don’t be shy.

I only recently began coming out to user groups and other dev-related events and I gotta say that writing code in isolation, no matter what you’re working on, isn’t nearly as fun as coming out and meeting other people with the same interests. So don’t be shy. Say hello to the person next to you, ask about them and tell them about yourself.

Conclusion

I came home from the camp both incredibly inspired and incredibly worn out. “Information overload” didn’t quite cover it. Now that I’ve had time to process, I can safely say that the event, for me, has been a blast. I regret being unable to stay for the afterparty and meet more people, but that’s something to fix for next year as well.

For now, I’m excited about the Microsoft Web Camp coming up on May 7 and 8. And after that… who knows?

Creating a New Application: First Lessons Learned

It may or may not come as a surprise, but writing software is hard. Having spent the last 3 years doing it for a living, I’m finally making time to develop a side project. I don’t have a proper name for it yet, but I don’t think I have to worry about that for quite a while.

I’m struck by how easy it is for me to write code at my job, where all products are in well-known locations and I’m very familiar with the code base. Creating an application from scratch is turning out to be a whole different animal.

I’ve been going back and forth on design decisions, agonizing over which features to start with and how to go about implementing it all together. And the main thing I learned is that writing code right away really is the worst thing to do. I made the mistake of ignoring that rule and paid for it by re-writing the same feature 4 or 5 times.

So below is my list of recently learned through experience things to know about writing a new application.

Lesson 1: Gather All Your Features in One Place

No, “it’s in my head” doesn’t count. Have a piece of paper or a text document that lists every feature you can think of. Then walk away from that list. Come back to it in a bit and read it over again — remove features that aren’t essential at first. Trim it down to the bare minimum that gives you a functional application. It may take a few iterations to get down to a short list of prime features.

Once that list is ready, prioritize core features over fancy “wouldn’t it be cool if…?” ones. And last but not least, think over every feature — what is needed to implement it? Will you need to pull in some third-party frameworks? Are there any particular design considerations or concerns?

Lesson 2: Figure Out All Workflows

For each feature on your short list, write out a detailed workflow. For example, in my application, the user can create new “To Do” items. So I write out that workflow:
1. Click File->New…
2. A dialog comes up where the user sets task parameters and notes.
3a. User clicks Cancel and the dialog is closed, discarding the information.
3b. User clicks OK and a new task is created.

I’d even sketch out the UI for each step, as needed. It helps.

Lesson 3: Write Some Tests!

It may be hard to wrap your head around how it will all fit together. The easiest way to get some progress is to write some unit tests. This will help you figure out what your classes might look like and help you arrive at a more easily usable interface.

Lesson 4: Don’t Settle on First Version of Anything

For each of the above lessons, I’ve found it helps to walk away for a bit and think things over. When you come back, you can look at things with fresh eyes and sometimes see things you missed the first time.

Lesson 5: Do One Thing At a Time

I find that I get distracted a lot while I code. Not by outside things like email or Twitter, but by tangential thoughts or ideas about what I’m doing. I keep thinking “oh, it’ll just take 30 seconds to fix up this one thing over here…” and before I know it, it’s been half an hour and I completely forgot what I was working on in the first place.

It is important to stay on track and on target. Make notes of things you think of along the way and schedule them in later.

Conclusion

It all boils down to staying focused and organized. Charging in keyboard blazing and starting to type out code will only slow you down in the end. It’s best to slow down, take stock of where you are and where you need to be, and form a plan to get there. Then work the plan and enjoy the feeling of productivity and motivation as you check things off and see your work produce tangible results.

But I shouldn't have to!

It amazes me sometimes how dismissive developers and advanced computer users can be of issues people have with applications. For example, FireFox 3.5 came out and Frans Bouma is reporting uncomfortably long start-up times on his blog. Now, I haven’t run FF3.5 myself and therefore can’t comment on my own experience running it, but I want to talk about a trend I’m noticing in the comments on that post.

Quite a number of people think it is acceptable to say things along the lines of “well, you should just clear out your cache”. Well, no. He shouldn’t. There is absolutely no reason for a user to change the way they work to accomodate an application as common and replaceable as a browser. For that matter, there should never be a reason to accomodate any finicky application, but I can see how in some niche markets that could be unavoidable. This is a problem in user experience design that seems to be quite prevalent, especially in the realm of open source development.

In a similar vein are posts on Coding Horror and bitquabit, calling out calling out developers for claiming a complex site like StackOverflow is “trivial”. Guess what, folks? As developers, we should be paying more attention to user experience, testing more scenarios, and not dismissing bad experience reports with nothing but a “oh, you should just use it the way we do and then it’s great”. It is naturally impossible to please everyone, but opting to use algorithms that do not depend on a state of the user’s system that’s completely outside the developer’s control seems to me a good start in the “consistent experience” direction.