Coding Style

We were having a fun debate today about coding style.

My style is:

if_(_condition_)
{
body;
}

However, I was informed that there was some mutiny going on and people were trying to over throw my spaces inside parenthesis in preference of:

if_(condition)
{
body;
}

I asked around a bit and found out another senior developer here uses this coding style:

if(_condition_)
{
body;
}

Oddly enough, when it's an if statement I like that space between the if and the opening paren. But when it's a method, I don't include it:

private void MethodA(_formal params_)

Without question I'm a huge fan of the spaces between the parenthesis. I find this makes code WAY more readable. After all, the parenthesis are entirely syntax. The stuff you care about is between them. When the stuff you care about is directly touching the syntax noise, things get a bit more cluttered.

However, a quick google search for C# coding standards indicates that this is a rare stance. From what I found, most standards seem to call for:

if_(condition)

My current style is influenced by style guidelines we have at work. However, if I had my way, I would go back to The Elements of Java Style guidelines and do my curly braces differently:

if_(_condition_)_{
body;
}

I had a professor in college who recommended that book's style guidelines. I hated them at first. But after about 2 days of coding with them I learned to really like it.

Sure, it's a religious debate... But I'm curious, what's your style? And what would your style be if you had your way?

Bug Reports

It turns out many people really struggle with writing bug reports. What I'm going to recommend here is exactly the same thing you'll find in the Joel on Software article, Painless Bug Tracking.

What I've found is if you go to someone and say, "What's the bug?", they'll have no problem describing it to you. But when they write the bug report, it comes out all confusing.

The difference is when I asked them "What's the bug?", they were happy to describe the bug to me. But when I ask them to report it, they feel like they need to tell me what the bug IS. Subtle difference, but it has a large effect. The result is typically a mangled sentence or two about how something didn't work. But it doesn't clearly tell me what they were doing or what they expected or even in what way it didn't work. Its like they are suddenly afraid to give me the context in which they found the bug.

So how do you write a bug report?
Just tell me these three things:

1. Steps to reproduce the bug
2. What should have happened
3. What happened instead
4. Provide extra details (exception text, error message screen shot, stack trace, etc)
   

The fun part about this is for many people they will save both time AND keystrokes reporting bugs this way because they no longer have to stress about "How do I communicate this bug?!"

For example,
1. Go to this form
2. Click on the "S'Okay" button
Error box should pop up, but instead the app crashes.

Crash report: blah blah blah blah blah...

You can use this method to report any kind of bug, you will save yourself time writing it, and you will save time trying to figure out what the bug is and how to fix it. Everyone wins, everyone is happy.

Check in Comments

My first approach to check in comments was not to use them. "You're just going to have to diff the code to see what really changed anyways!" I would have said.

My second approach has changed a bit. I still think you're going to have to diff the code to see what really changed. Like I talked about in Code Documentation, meta data is a bad substitute for reading code. However, check in comments can help answer the following questions:

1. What did that dude change?
2. Which files do I need to diff?
3. Could this change be of interest to me?
   

The key is you have to write your check in comments to be helpful in answering those questions and leave the details to the diff.

1. If you didn't really change anything, don't leave a comment. If you're checking in a file and all you've done is change the spelling of a variable, or the capitalization of a method, or the wording of a comment, don't bother with the check in comment. No one is ever going to need to diff or read your changes for that version, so save me the time in reading your comment just to figure out that you didn't change anything, and don't leave a comment. If you're required to leave a comment, just put "none" or something equally simple.
   
2. Title what you changed. Pretend you're trying to give the diff between your version and the previous version a Chapter Title. It should summarize the changes you've made at a high level.
3. Be as brief as possible. Don't write a book. Don't even use full sentences. How few words can you use to describe the changes you made?
4. Group check ins by change. If you're checking in 10 files which have had 5 mutually exclusive changes made to them, don't check them in all at once. Do 5 check ins of two files each. Each check in gets its own comment describing only the changes in those files.
   
5. Check in one change at a time. If you're frequently writing check in comments that say, "Did this and that," could you have done "this" and checked in, then done "that" and checked in?
   

One example of a bad check in comment I frequently see is a list of everything that was changed, written in one run on sentence. For example, "Updated the <class> to have 3 new public methods, and broke <method> into two different methods, one for <a> and the other for <b>. Also changed the parameter types of the methods from <x> to <y>." There are a number of things wrong here. First, why should the check in comment document the purpose of the methods? I'm going to assume there are comments in the code you're checking in that does that. Second, why tell me about the actual parameter types you changed from and to? It's probably enough just to say the parameter types changed. Third, do I really need to know the class, and method names? And finally, this is too long to help me figure out if I want to look at this version of the file. You could convey all the information needed by saying "Refactored public interface" or if the refactoring has added new capabilities, "Supports a, b, and c."

A check in comment should convey what changed at a high, abstract, level. To figure out how those changes were accomplished: diff. To figure out if those changes might be causing a bug you just found: diff. To figure out how to use the changes: diff. You're better off looking at code to answer those kinds of questions anyway. The check in comment is just a guide to help you figure out where to look.

Code Documentation

At work I've worked with a lot of people who are either just out of College or still in College. There has been an interesting trend in their code's documentation: they like a lot of it.

I'm guessing that they were taught that code had to have comments and they were probably deducted points if they didn't have any. However, they weren't deducted points if they wrote bad comments and they weren't granted points if they wrote good comments. My guess is no one ever told them what the difference between a good comment and a bad comment was. So usually one of the first things I try to teach is what my guidelines for comments are.

1. Meta data is a bad substitute for good readable code
2. Write future proof comments. Don't write a summary comment that says what each step of your method will be. This is guaranteed to be out of date when someone else changes your method's code and forgets to update the comment. Now your comment is a lie.
3. Tell me what your methods, properties, or objects will accomplish for me. Don't tell me how to use them. I can determine how best to use it once I understand what it does.
4. Only current code matters, what the code did in the past is not important. Don't document history in your code files.
5. Add line comments if the line is confusing or needs clarification. If it's clear on it's own, don't clutter it up with a comment.
6. Break code into methods instead of using large or intricate commented sections.
7. The shorter the better
   

Two things drive all these guidelines:

1. The goal is readable code
2. Its better to read code than to read meta data
   

If your code isn't readable, you're going to be afraid to read it, and that's a problem because its better to read code than to read meta data (and comments are just meta data). Why? The meta data may be out of date, or it may not accurately represent the code. In the end, it doesn't matter what you think the code does, it matters what the code actually does. The best way to determine what it actually does? Read it. That doesn't mean you can get rid of all meta data, because you can't. But you can be very careful with what meta data you create and what content it contains.

The main purpose of summary comments is to clarify what code is meant to accomplish when the name may not be sufficiently self explanatory. This will help people (including you) figure out how they should use that code. If they want to really understand what it does, they'll have to read it, but if the summary and name are written well enough they should understand enough to take advantage of its functionality.

The main purpose of line comments is to clarify code that may be harder to understand for some reason. This could be to describe why something is necessary (like a hack). Or to explain the effect a line will have on a line somewhere else (like to cause a loop to break).

There are cases where you may need to not follow these guidelines, that's why they're guidelines. However, in most cases they've served me well and helped me produce cleaner and more easily understood code.