The Community For MVC.NET will be running a Live Meeting with Phil Haack on August 26th @ 9am PST (4pm GMT / 6pm CET) on upcoming MVC 2 features.

Even though I don’t develop software in SharePoint, this blog post by Lee Richardson reflect my thoughts and worries about SharePoint development.

The essence of his post is in this paragraph:

But the power given to end users makes rigor and good design extremely hard for developers because the production machine you deployed to last month may look completely different now that you’re ready to redeploy. And Microsoft makes good design even harder with an inflexible API. Critical classes like SPSite (think SqlConnection) contain no public constructor, rendering them completely unmockable (unless you’re willing to spend $450 per developer for some TypeMock Isolator magic). And vital classes like SPList (think DataSet) are marked final, crippling your ability to make nice strongly typed entities in your architectures.

Lee proposes some techniques to use that you should read in his post, but it’s half baked and not good enough in my opinion. The things he suggests (which is usually taken for granted on any other project) is made really hard to do by MS. Should MS rethink the way SharePoint is architected for the sake of developers to ease maintenance, improve code quality and basically allow developers working with ShapePoint to be craftsmen? Or is the dynamics of the product given to the end user so good that it’s worth all the extra efforts?

A couple of days ago, my article about “The Current Direction Of Agile” was published on InfoQ. The article mainly represent my own learning curve within agile and lean inspired processes, hoping that my view would be interesting to others. I feel the recent Lean inspiration that agile has gotten the last couple of years, has pushed the agile community into a better place and been given tools to improve agile further.

Thanks to David J. Anderson and Arlo Belshee for reviewing the article, and not to forget Amr Elssamadisy @ InfoQ for pointing me in the right direction.

It’s tempting to just leave this blog post with that statement only :-) I will however explain this a bit further for those of you who either are forced to write comments (like by your boss or a policy at your company), or actually believe a lot of comments in code increase readability and ease maintenance.

I’m not trying to be sarcastic, I just believe 100% in code and not in comments. In .NET and most other OO languages there are two types of comments. The first type is the one you write in your code to explain what your code does. Like this:

//Calculate interest

double amount

    = balance * Math.Pow(1 + (annualPercentage / 100) / 365, days)

      - balance;

How do you replace this comment with code? What about this:

double amount = CalculateInterest(balance, annualPercentage, days);

Whenever you come across comments like the above, I encourage you to refactor by replacing comments with code. Often you don’t even have to extract a method like above, but just give better names to variables.

The second type of comments is the ones you use to generate API documentation:

/// <summary>

/// Calculate interest

/// </summary>

/// <param name="balance">Current balance of the account</param>

/// <param name="annualPercentage">Annual percentage</param>

/// <param name="days">Days to calculate interest for</param>

/// <returns>Interest amount</returns>

public double CalculateInterest(double balance,

                                double annualPercentage,

                                int days)

{

Almost on every project I’ve been on we’ve had these comments/documentation. Also, on the same projects they’ve never been used for anything useful. I’ve actually forced devs to do this myself! If you’re creating a product/framework to be used by other devs, writing this type of documentation makes sense. If you don’t, it makes no sense! I used to do this just to satisfy my own satisfaction of generating a chm file and see that all my methods and classes was documented. That was about it. I never used it once! It’s much easier to look in the code than to look at the API doc.

The worst thing about this type of documentation is that it clutters your code and makes the code hard to read. A class with 50 lines of code becomes 100 lines with comments. As a practice, try to remove all comments and see if it’s easier to understand and read the class. I strongly believe it is. If not, it’s a code smell and you should refactor your code! Comments should not be used to explain bad code.

When I talk to people about comments in code I often ask them two questions:

Do you think it’s hard to maintain code?

How hard to you think it is to maintain comments?

If you change your code, do you also make sure to check if the comments are still correct after you’ve done the changes? Most people don’t and you shouldn’t really need to worry about it. Outdated comments can create confusion and bugs just because someone forgot to update them.