I was recently discussing the value of comments in code with some colleagues. After the discussion, one of them sent me a link to "Don't Waste Your Time Commenting Source Code" written by Riyad Mammadov.

I have to say I'm both shocked and disappointed that there are developers out there that have this opinion. And there seems to be quite a lot of them. I'm quite passionate about code comments because I spend the huge majority of my time maintaining/debugging/fixing code written by other people that has no comments (other than commented out code...). I waste an enormous amount of time stepping through code with a debugger, just trying to understand WTF it's trying to do.

I know some developers that always respond "The code is self-explanatory". This is a garbage excuse from a lazy programmer. There are a few reasons why this argument is not valid:

1. It might be self-explanatory to you, but there are other developers here that may need to maintain your code, some less skilled than others.
2. Unless you're a compiler, reading an English comment is far quicker than parsing code in your head.
3. It's rarely clear from code why it does what it does.
4. Reading code only helps you understand what it does, not what it was intended to do. This would be fine if you wrote flawless code. You don't.

In addition to this, we often have to write less-than-ideal code. You might find a bug, and to work around it, change some nice clean code to something a little bit hacky. If you don't comment why, there are good chances that someone will come along, think "WTF, this could be done better" and refactor your code, re-introducding the bug. A simple comment saying "Can't do this using X, because it causes Y to fail" could save a lot of time and effort.

Back to some of the points made in Riyad's article...

I strongly believe that 90% of source code comments are a waste of time

I think Riyad is a little confused between code with crap comments, and code that doesn't need commenting. I can't possible agree that only 10% of all code written is worth commenting. I might agree that only 10% of code comments are useful, but that just means the developers are failing at writing good comments, not that the idea of writing comments is bad. A huge portion of useless comments on code could be replaced with useful comments.

if you think about it, a well-designed program doesn't need comments to be maintainable

This really is tripe. Code does not convey the *reason* you are writing it. Here's an example from some real code:

// When the transition finishes, hide the screen. We don't remove it,
// because we want it to come back when the covering screen is dismissed
this.ScreenState = ScreenState.Hidden;

Without the comment, it might not be clear why the screen is being hidden, instead of being removed. Somebody that's not familiar with the code (which, six months after it being written, is everybody, including the author). The comment makes this pretty clear why the code does what it does.

If the choice is between a well-designed program without comments and a thoroughly commented but poorly architected one, I will choose the former any day of the week

I don't understand the logic here. There is some suggestion that writing comments comes with a penalty that somehow affects the architecture of your system. I think a more valid comparison whould be "Unfinished, but commented code" vs "Finished, but uncommented code", and I would absolutely take the commented code any day. It's unlikely that it'd take longer to finish a well written, well commented application than it would to try and understand thousands of lines of uncommented code.

Riyad shows some sample code to illustrate his point:

/**
 * Always returns true.
 */
public boolean isAvailable() {
    return false;
}

There's no argument here. This comment is pointless. However, there's some suggestion that because this comment is pointless, this code does not need commenting. That is absolutely not the case. The comment is crap. It should be replaced with one that is not crap.

Not writing code comments because some people write crap comments is like not writing code because some people write crap code.

Sadly the biggest loser in all this is not the developer that's not writing comments, but his colleagues. They'll struggle to maintain his uncommented code while he easily understands their well-commented code :(

Update (19th March): I've added some additional info I received at the end of the post.

It's been a funny week. My blog usually receives a few hundred visitors per day. This weekend, I published a post titled "Why I'm Close to Giving Up on Windows Phone 7, as a User and a Developer", sharing my frustrations with Windows Phone 7. I hoped that someone from Microsoft might read and respond to it. I wasn't really expecting the attention the post got during the last 24 hours.

The post had over 40,000 visitors in a 12-hour period yesterday (which cost me exactly £0.00 in hosting - go App Engine!) and was republished by BusinessInsider. Today, I had a call with Brandon Watson, Director, Dev Platform & Ecosystem and Ben Lower, Senior Product Manager, Dev Platform & Ecosystem.

This was somewhat unexpected.

Given they'd taken time to call me, I thought it was fair I take time to post some of the things we discussed (I hope I understood them right - the line was pretty bad). It sounds like they're taking the feedback seriously and didn't seem too annoyed with the bad PR I might have created.

Weak UK Launch / Knowledge of Operator Employees

The fact the UK launch was weak (to say the least) didn't sound like a surprise to Brandon. He explained the marketing budget was of course much smaller than in the states and that it's difficult to get info into shops (Microsoft are far divorced from the stores).

This certainly explains the poor support my colleague got from Virgin, who didn't seem to know what the Zune software was or why there had been an update. However, I wonder whether this is the whole picture - it seemed to take a long time for stores to even start getting their first handsets, so I still wonder whether a problem supplying the devices resulted in a deliberate reduction in marketing during the first few weeks.

I think this is something Microsoft must work to address. Apple have their own stores across the country, so the people selling the devices are their employees. Microsoft don't have this luxury and will need to work far harder to ensure the same quality of information and hardware availability at point of sale.

Retrieving Error Logs from Retail Devices

I brought up the issue of my SMS bug. I was willing to help Microsoft to try and diagnose the issue if they could get logs from my device. Brandon pointed out that the real issue here was that the parts of the software that allow sending of logs to Microsoft are removed from retail builds of the OS - only developer builds are able to do this.

This seems a little naive to me. There are a ton of developers out there that are very good at reporting bugs and they'll almost all have retail devices with a retail build of the OS. Brandon said he'd discuss the possibility of having this functionality included and enabled when a phone becomes developer unlocked. I think it's really important this is done if Microsoft want to be able to track down and resolve issues in a timely fashion.

SMS & Bluetooth Bugs

Brandon said he'd try and find out whether the SMS and Bluetooth bugs I specifically mentioned may be fixed in NoDo. I'm not too fussed about the SMS issue (it's never happened since), but the bluetooth issue happens daily and is so annoying to me that I'll seriously consider swapping phones if it's not addressed soon.

No Way for Users/Devs to Report Bugs

I was really frustrated with not being able to report bugs in WP7 to Microsoft in a structured way. Developer-focused products at Microsoft use Connect, but WP7 seems to be excluded. People are more than happy to help by submitting bugs, if they knew where to send them!

Ben suggested the idea of using a service like UserVoice to allow collection of issues and voting. I'm not sure why this would be better than Connect, but it sounds like a reasonable idea. Even a wiki page would be better than the "current system"!

I had a quick search and noticed there's a Windows Phone 7 Community UserVoice forum already. Not sure if this is official in any way, but if not, I do hope an official account is set up and monitored by Microsoft.

Slow Updates

This is quite a big one, but sadly, the one with least info. I suggested it was ridiculous that such a big company can take so long to get an update out. Brandon pointed out that in reality, bigger companies move slower. I don't really think this is a good excuse - if policies and processes mean it takes 5 months to release an update, then the policies and processes need improving. If a big company can't work as efficiently as a small company, then the big company should act as smaller companies.

You probably saw the recent blog post by Eric Hautala. He's the new guy, and his job is delivering updates. Eric's appointment looks like acknowledgement that Microsoft know they have work to do in this area, so we'll have to see how things evolve.

No Visibility of Incoming Fixes / Release Notes

I raised the issue of nobody knowing what's in NoDo other than the few features that have been announced. Brandon agreed that some sort of release notes should definitely be included (and are, for many of the development products) and said he'd look into it. Apple provide release notes for all of their updates, though I'd prefer to see Microsoft go one step further and publish them before the update. If Microsoft need inspiration, they should take a look at how Blizzard manage releases for World of Warcraft; Patch notes are posted and updated constantly before launch, and go into great detail. I'd love to see this kind of transparency from Microsoft.

I think I've covered the main points we discussed. The conversation was positive, but it was only talk. It'll take time to see whether Microsoft is really moving forwards. If I receive any additional info or responses from Brandon or Ben, I'll post about them.

One thing is clear from this experience; Microsoft care about developers. Apple failed to respond to the massive WiFi issues in iOS4.2.1 during the 5 months it took them to fix it, whereas within 24 hours of my post getting attention, I'd been contacted by around 6 Microsoft employees, including Brandon Watson. Let's hope the enthusiasm for getting in touch with me turns into results.

Update (19th March):

Since posting, I received a little additional info:

Connect is still being used for Windows Phone 7, though it is restricted to certain closed/invite-only programs (eg. for MO/OEMs/Devs that had development devices pre-launch). A public connect will require a better structure to deal with the volume of cases. I got the impression this is being evaluated, though no commitment.

UserVoice is also being evaluated as an option for user (non-dev) feedback. Fingers crossed if this doesn't pan out, we get an equivalent at least.

It seems that these guys agree that being big isn't an excuse for being slow, and they're committed to improving things and making things move efficiently.

MIX. April 12 - 14, Las Vegas. ;)

Also - Brandon sent me a link to the Windows Phone 7 update schedule. There's some excellent info there. I looks like MS are really taking user feedback onboard - this gives me faith :-)

Update: A few days after posting this, I had a call with Brandon Watson, Director, Dev Platform & Ecosystem and Ben Lower, Senior Product Manager, Dev Platform & Ecosystem. I've posted a little update here.

Note: This is a pretty long post, but it's the only way to get across why I'm suddenly so disappointed in Windows Phone 7 - a platform I've been so excited about for so long. I really hope someone on the WP7 team takes the time to read it to the end. I'm probably not unique in having these feelings.

It's a harsh title, so first, a little background...

I've been waiting for Windows Phone 7 for around 10 years. Really! See what I did there? :)

In 2001 I finished my A-Levels and got a job as a web programmer. I lived with my parents and had plenty of cash to wastespend. One of the first gadgets I bought was a Compaq iPaq. I convinced myself that it was really useful, and that it saved me lots of time, but in reality, it was horrid. The Windows operating system was slow and sluggish and the usability was pretty awful. I had to buy a sleeve that made the device twice as thick and a huge WiFi card just to allow it to connect to anything. It was crap, but I loved it anyway.

When Microsoft released the .NET Compact Framework, I was so excited. I could now write my own applications to run on this device that would fit in my pocket. Awesome! Except, it wasn't. The device was still a pain in the ass to use and the performance still sucked. The ideas were great. The execution was terrible.

It wasn't long before I picked up an XDA, so I no longer had to carry both a mobile phone and a PDA. Good times! Or not. The mobile version of Windows was still pretty bad.

Over the coming years, I bought practically every Windows mobile device I could afford. I lived in hope that this new device would be nice and snappy, and Microsoft will have improved the OS and added functionality. It never happened, but it didn't stop me throwing money at them each time, in hope.

Fast forward a few more years, and I'd been playing with Managed DirectX. The idea of programming games in C# was pretty exciting. Ultimately this became XNA, and the Zune wasn't far behind. I really wanted a Zune, but the UK launch was delayed and delayed, and ultimately never happened.

When Apple released the iPhone, I started to wonder if the reason we hadn't seen a Zune in the UK was that Microsoft were holding back to release a ZunePhone. Despite waiting and waiting, this didn't happen.

During this time (since 2001), my career was built on building web applications in Microsoft technologies. My life is well and truly in the Microsoft camp. I love .NET, I love C# and I love Visual Studio. It made me die a little inside every time I had to do some work in PHP or fire up Eclipse...

However... In 2008, I ditched my Windows-based XDA and bought an iPhone. Sorry Microsoft, I'd been waiting for 7 years, and you still hadn't delivered.

I loved my iPhone. It made me sad that there was no competition from Microsoft. I even started working on iPhone apps. I really hate Mac OSX, Objective-C, and XCode. But I had to go with the market.

Imagine how excited I was when Microsoft announced Windows Phone 7! I can ditch this Apple nonsense and develop applications in C#, Visual Studio, XNA, Silverlight! Finally, Microsoft are putting their weight into a promising mobile platform. Despite previous failures, this time, I have hope that they can really do it.

Through my company, I was able to get access to a developer WP7 device from Microsoft. The hardware was a little shoddy, but the OS was very promising. Everything was looking good!

I'd convinced my company we should be working on a Windows Phone 7 version of our iPhone apps, and I resisted picking up an iPhone4 because Windows Phone 7 was the way forward. I kept my eyes open for a UK launch date in the hope it wouldn't overlap with my holiday in Orlando, so I could get one right away. As luck would have it, the launch was announced as a few weeks before my holiday!

This is where it started to go wrong...

As we got closer to launch, I noticed there seemed to be a huge lack of advertising. I started to doubt whether the launch would be met at all. I started calling around local stores, and nobody knew anything about the launch. WTF? How can they not know about Microsoft's competitor to the iPhone?! I popped into a Carphone Warehouse over the road from the office where I work on launch day. The staff knew nothing about WP7. I called all the local Orange stores, hoping for a HTC Mozart. Nobody knew when, or if, they would be getting any Windows Phone 7 devices. Wow.

I wasn't giving up that easily, so I spent the next few weeks (getting close to my Orlando holiday) trying to track down a device. Eventually, I found that a local O2 store had HTC HD7s in stock. I rushed down there, and managed to convince them to sell me one as Pay-As-You-Go (since I'm on, and very happy with, giffgaff). I was made up! Windows Phone 7 was awesome. Just being able to pin a tile for my wife and see calendar appointments on the homescreen was enough for me to purchase it over an iPhone!

Then I went on holiday to Orlando. I took loads of geo-tagged pics, and was genuinely really impressed with the phone. Congratulations Microsoft. You've finally done it. But still, where is all the fanfare? You need to show people how awesome this phone is - then you'll sell bucket-loads!

As time went on, cracks started to show. There were bugs. Many bugs. At one point, the SMS message store for my wife got corrupt, which meant I couldn't send, or read, text messages to/from her. I got in touch with the UK WP7 developer advocate that had sorted out the developer phone for my company, and explained the issue. After many emails going back and forth I was told that there may be logs on my phone that would help Microsoft track down this issue but security procedures do not allow them to share a tool to get the logs off my device. I was instead, told to try a factory reset. This fixed the issue, but Microsoft were no closer to finding/fixing the bug.

Another pretty annoying bug was that the bluetooth randomly disconnects from my car. Frequently. About every 2-3 minutes. If I'm on a call when this happens, the call stays open, but just normally via the handset in my pocket. As you can imagine - I can't hear the person at the other end, and they can't hear me. 10-20 seconds later, it reconnects, and the call continues.

Because I preferred coding in VS/C# so much, I started work on a Windows Phone 7 game in my spare time. I even got a few colleagues to join in by creating their own games, as part of an XNA coding competition. Most of these guys had never even coded C#, never mind written a game!

My game is called Badger Quest, and currently has a few playable levels. There are no videos online yet, but you can see how it looks from the background on the Twitter page. It'll be pretty similar to Mario, though played by tapping buttons on the screen to use your abilities (jump, turn, throw, slash, etc.) which are limited in number.

As time went by, I started to have doubts. WP7 handsets weren't selling very well. The marketplace was buggy (eg. returns to the "Xbox LIVE" filter when you press "Back" from looking at an "indie" game). I started to wonder how seriously Microsoft were taking their platform. The OS was great, but how they responded to initial feedback and bug reports (and how quickly) would ultimately decide the fate of the platform.

With a huge outcry over the lack of Copy & Paste, Microsoft announced there would be an update in January that would add this. Excellent - if we don't get the bugfixes before then, they'll be in that update. All will be good.

Sadly, it wasn't good. The update was delayed. And delayed. There was zero transparency from Microsoft. Despite the rest of the company making huge strides in this area over the previous few years, Windows Phone 7 is a quiet, closed box. Nobody knew what was happening with the update, and more importantly, the bug fixes.

Eventually, an update started to roll out. Yay! Only, we quite quickly discovered it wasn't NoDo. It was a pre-update update. An update that updates the update system. Why couldn't this just be bundled with NoDo?! More annoying was that Microsoft didn't announce this update until after they started pushing it. They told us nothing about what it did.

Then it got worse. One of my colleagues was prompted to install his update. He connected his phone as described, and the update started. Then it failed. It gave an error saying his phone was not updated, and could not be rolled back. He tried all sorts of resets, with no luck. His phone was bricked. As I'd been one of the people that had suggested he get a WP7, I felt pretty bad. He spent the next day being bounced between Microsoft, Virgin and Samsung, trying to get his phone working. During this time, he could not use his phone in any way. The staff at Virgin and Samsung knew very little about WP7 and more specifically, this update. Eventually, Virgin agreed to send him a new handset.

Fast forward a few more days, and we're all still waiting for NoDo, and our bugfixes. It's been over four months and we've still had zero bugfixes. Rumours start spreading across the web that NoDo has been delayed. Again, it takes a week before Microsoft finally come out and tell us what's going on.

Hopefully if you've read this far, you now know why I'm starting to have serious doubts about Windows Phone 7. If Microsoft can't turn around bugfixes in a timely fashion, what's going to happen when people start finding exploits (and they will find exploits)?

Of course, if I'm not confident in the platform as a user, I can't be as a developer. I've put my Windows Phone 7 development on hold. I can't commit to spending more time on a platform that Microsoft seems to be sending the way of previous versions. I still believe the OS is excellent, but sadly, that's only half the battle.

I'm not giving up, just yet. I truly believe Windows Phone 7 can be something brilliant, but there are definitely issues that need addressing. To show how seriously I believe Microsoft could make this work, I've applied to go and work for the Windows Phone team via the Microsoft Careers website. If Microsoft want to make Windows Phone 7 better, here's an offer for another set of hands to test the platform. I'm serious - I'd relocate from the UK to the US to help work on making Windows Phone 7 better, because I think it could have a strong future.

A few months ago, I posted about (and updated) the news of the Windows Phone 7 Marketplace separating "managed portfolio" games (eg. those that have relationships with Microsoft - generally the bigger games developers) and "indie games" (created by you and I). I was concerned that the lack of XBLIG sales would continue in the WP7 world. Now that the Windows Phone 7 Marketplace is live in the Zune 4.7 software, I thought I'd post an update on how things turned out.

When first entering the apps section of the marketplace, the intro screen is comprised of four sections. The top one (largest) looks like a list of Microsoft-chosen list of apps, similar to Apple's featured/staff picks section. Just undernearth, slightly smaller, is a "We recommend" section. It's not entirely clear what the difference is here - it's possible that this is just one list, and the top four simply get bigger icons. It's not clear whether either of these may ever contain indie games, though I'll try to get clarification. The remaining two sections are top selling lists, which do include indie games, one of which can be seen in the screenshot below.

The landing screen is not restricted to games, so for the games section, you'd click the "games" option on the left side of the screen. This brings you to the games section, which can be filtered to All, Paid, Free, Xbox LIVE. Notice that the default section is Xbox LIVE. This section is restricted to managed portfolio games, which all have full access to the LIVE APIs. You can easily identify these games by the "XBOX LIVE" banner at the top of the icons.

Clicking the "all" option, will give you a full list of all Windows Phone 7 games. There are subgenres in the bottom left, but this list contains both managed portfolio games, and indie games. Hurrah! No navigating to the indie bin!

Clicking the "paid" option, takes you to a section that is exactly the same as the "all" option, but shows only games that cost. Again, indie games sit side-by-side with managed portfolio games here.

Clicking the "free" option, as expected, takes you to the same again, but shows only games that a free to download. Again, indie games sit side-by-side with managed portfolio games here.

Conclusion

In summary, I think this is an excellent structure. Defaulting to the Xbox LIVE games is a great choice for consumers, and outside of this section, it looks like indie games are treated equally. This eliminates all concerns I had, and I can't wait to finish Badger Quest and get it up there!

Yesterday I posted some info that suggested a two-tier Xbox LIVE marketplace on Windows Phone 7, and that I thought it was a massive mistake on Microsoft's part. Today I had a lengthy chat with Paul Foster, a Microsoft Developer Evangelist, about that post. He wanted to give some more details about how things worked to avoid me having to draw my own conclusions.

We went into Xbox LIVE publishing in great detail, and I decided to get Paul to confirm some of the things we discussed by email so I could post them here, for those that had read my previous post and were worried. Paul was unable to answer all of the questions (due to various things being hush-hush at this time), but said he'll answer them when he can. Below I've included his answers, along with the outstanding questions we'll hopefully have answers for in the future!

Q: Will Microsoft engage directly with small companies/individuals that have great games, ready to publish (to become part of the managed portfolio)?

A: Microsoft's XBL team and importantly a range of 3rd party XBL publishers are looking out for new opportunities, in fact at GDC 2010 and Mix10 the wpgames@microsoft.com alias was advertised asking for indie games devs to submit their game concepts they are building. The important point here is that if you want your game to be a big success you have to do more than just post it into an app store. You need to think about it as a manuscript for a book and take it around various publishers to get opinion and seek publishing opportunities. Publishers have the skill and capability to market your game and find bigger publishing opportunities – such as XBL. Publishing by default into an app store isn't enough for success when big numbers of people are doing just that – you need to do more than just develop your game, you need to drive the commercial publishing of it and the ecosystem of XBL provides broad opportunities for publishing. If after doing all that, the best opportunity for you is to publish straight into the marketplace then work at advertising your game. Seek magazine or blog reviewers, publish videos of it and ensure you have a cool web landing page for it. None of this stuff costs much and can raise the profile of your game.

Q: How are managed/unmanaged portfolio games separated in the store (visually/category-wise)?

A: All apps/games are in the single app store, filed by various categories. There are various merchandising locations in the marketplace and in the Games hub – these will be driven by various metrics from the store as well as for apps/games of planned marketing activities.

The following questions are unanswered as yet, but it seems like the answers will be positive for indies!

Q: Will there be separate "top sellers" / "what's new"-type lists for managed/unmanaged portfolio games, or combined lists?

Q: Are managed/unmanaged games separated in search results (if I search by name)?

Q: Will there by managed/unmanaged portfolios of apps too, or games only?