Header image alt text

simon collis

musings of an omnivorous biped

Comment your code, people

Posted by simon on 2013/02/17
Posted in Technology  | Tagged With: , , | No Comments yet, please leave one

Ars Technica recently posted an article taken from Stack Exchange about comments in code. It’s a thorny subject with programmers. “Why should I comment my code – I know what it does?”.

Sure, you do. But what happens if I need to come and work on your code – in a hurry?

I’m speaking from experience here. Bitter experience. I’ve had to dive into code, in a hurry, to fix something, because a client is on the phone, screaming, and screaming loudly that this needs to be fixed. Today. Or There Will Be Consequences.

And the code was horrible. Layer upon layers of classes with cryptic but “self-descriptive” names. Sure, he was following the “Code Complete” method of working – “regard every comment as a personal failure”. “Clean Code” has the same thing.

Here’s a tip for you: take those two books, find the pages where it says this about comments, and cross it out. Because while both books are incredibly useful, they are completely and utterly wrong about comments. Their advice is harmful, dangerous, and leads to sloppy, unmaintainable code. It promotes a sheer lack of professionalism, and it’s dangerous. If either of the authors came to me for a job, I would turn them down, even if I were short staffed and they were the only candidate, for this reason, and this reason alone.

What I needed in that circumstance wasn’t “self-documenting code”, what I needed was signposts – I needed to be able to find my way to the trouble spots – fast. Even single-line comments giving a brief description of what the class did would have helped. I’ve worked on badly written projects that were more maintainable than ones that are paragons of excellent code entirely due to this issue. I’d take a well-commented, bug-ridden crawling horror over some comment-less mediocrity any day.

Comments are not a failure, nor should they be regarded as such. One answer they mention in Ars demonstrates exactly and precisely why comments – even bad ones – are essential, without even realising it. Take a look at this, from an answer by Paul:

They often lie. You cannot trust comments and must read the code instead. Which raises the question: why would you need the comments at all?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
//the calculation of the hash
int result = a*b;
}

(The hash is not the sum but the product.)

Sure, that’s a bad comment. But it documents what the programmer was expecting the code to do. If this is where the error is found, then it should raise alarm bells. Check your source code control logs (you do use Subversion, TFS, git, or something like that – right?). Is it simply a typographical error? Did it get changed for debugging and nobody changed it back? Did it get changed – even though it’s wrong – to get a badly written test to pass? I’d argue that the comment isn’t wrong here, not at all – it’s a clue as valuable as the curious incident of the dog in the night-time.

But let’s diverge for a moment – what if the comment were more illuminating?

// this method used to return the sum of 'a' and 'b'

or how about the even more useful:

// this method used to return the sum of 'a' and 'b'
// 1999.09.09 (SC) changed to be compliant with protocol v2

In reality, I don’t think anyone that doesn’t comment their code can, or should, ever be called a “professional” programmer. I’ve worked with many bright minds who develop over-complicated systems that have caused their colleagues problems when the inevitable happens, and they have to take over the maintenance of the project.

It’s not for nothing that Microsoft StyleCop bitches when you don’t comment what your code does. Much as I don’t particularly enjoy working with StyleCop’s rules, that’s one I’m totally in favour of.

In short folks, my attitude is simple: either learn to write effective comments, that signpost what the things you have written are supposed to do, or go find a job doing something else. Because until you can write effective comments that enable other people to modify your code, you’re not a professional who makes positive contributions at work – you’re a dangerous liability who is endangering your employer’s very existence.

Rant over.

Ars Technica makes a pretty good case that the sales of Windows 8 are pretty good so far. On a par with Windows 7, in fact – the Wall Street Journal estimated 40 million copies were sold in that first month for Windows 7 too. So everything looks peachy, right?

Not from where I’m sitting. Here’s the problem as far as I see it.

Windows 7 – like Vista – was launched with a special discount: everyone who’d bought a PC in the last 6 months got Vista at a serious reduction – the cost was £12.99 in my case, which is basically the cost of media and shipping and handling. The same discount applies to Windows 8, too.

The difference is that Windows 8 also has an “early bird” discount, too. When it came to Windows 7 or Vista, you paid a lot more without the “recent PC” deal, but there is for Windows 8 – right now I can upgrade for £24.99 (the price on the US site is $39.99).

It doesn’t take a maths wizard to work out that this is only a third of the income for Microsoft. But also it doesn’t take a genius to work out that this discount isn’t making any difference. The people that bought Windows 8 so far are much the same ones that bought Windows 7 last time around.

Of course, it’s too early to tell exactly what the implications of this are, but it represents a real opportunity. For Apple, for Android, and for desktop Linux. For someone like me, who’s spent an entire career developing with Microsoft products? Well, let’s just say I’m not sleeping as well as I used to…

Simon’s quick, capsule review*: annoying.

The new address bar highlighting is intrusive. So much so, I’ve finally turned the address bar suggestions off (as well as the search suggestions). Bold text was OK, but the unpleasant looking grey highlighting has become annoying very quickly. Sadly, I can’t find a way to turn it off.

At least I can turn off the protocol hiding and the highlighting of the domain in the address bar, but it would be nice if there was a way to revert to the older look of the address bar search, because I preferred that. It’s a shame they don’t provide the option.

Oh well… one more reason to switch to Google Chrome, perhaps? (Oh wait – you can’t unhide the protocol on Chrome…)

* – NSFW

Google Android is the worldwide leading smartphone OS in terms of shipments. I don’t think anyone would dispute that. iOS is the leading smartphone OS in terms of developer revenue, and I don’t think anyone would dispute that either. That Apple hates Android and would like to kill it – well, that may have been true under Steve Jobs.

But things are changing – Apple are introducing 4G, and beefing up Siri. Voice recognition and voice search are areas where Google do have quite a big patent portfolio, and both Google (through Motorola) and Samsung have 4G patents. So this could run and run.

The problem is, as has been pointed out in a few news sources, the Apple v Samsung trial hasn’t really hurt Samsung’s image, whereas even the Apple faithful are turning on Apple over this one.

If they keep hitting out at each other, there can only be one winner – Microsoft. Read more

I’ve been looking at the Apple TV for a long while now, and I keep thinking that I both want one, and I don’t. Let me explain…

First off, the one I really like the idea of is the Apple TV V1. It can contain movies, be synced from iTunes, and contains a hard drive. So I can keep a range of movies – and I’ve spent ages acquiring a collection from the Internet Archive of vintage stuff I really want to see – on the Apple TV and just watch them. That feels like the sort of device I want. But… Read more

The results are in, and it’s a massive win for Apple against Samsung. At least, for now.

First off, there will be appeals, of course – there always are. It’s highly unlikely Apple will see the full damages – and they’ve annoyed a major supplier into the bargain.

But before Apple fans get too excited, this little tiff could have some serious downsides for Apple. Read more

What does “&amp” mean?

Posted by simon on 2012/08/12
Posted in Technology  | Tagged With: , | 19 Comments

Tonight, Suzanne Moore asked on Twitter what “&amp” means. Any technological readers of this “blog” (and I use the term quite wrongly) will already know, but if you don’t, here’s a short explanation…

Web browsers display their pages using a language called HyperText Markup Language. That’s a lot to say each time, so everyone I know that uses it day-to-day calls it “HTML”.

When it was developed, back in the early 90s by Sir Tim Berners-Lee, there was a major issue – different computers use different character sets. What happens to be a pound sign on one computer is a hash symbol on another. Read more

Here’s a thought I’ve been thinking for a few days.

Like many of the rest of the Google fanboi sheeples, I laid down a goodly sum of cash for a Nexus 7 the moment it came out. What’s to like? Well, first off, the screen is nice. Really nice. Better than the iPad 2 – maybe. Better than the iPad 3 (sorry, new iPad)? Not so much. But it’s close. Read more

All Surface, No Feeling?

Posted by simon on 2012/07/16
Posted in NewsTechnology  | Tagged With: , , , , , , , , | 1 Comment

Microsoft just took a huge gamble. A mega big one. And I’m not sure if they’ve already lost.

Let me start with the background. A few months ago, they announced Microsoft Surface, a shiny Lumia blue tablet thing (apparently it’s hit production problems already – who’dathunkit?)

Today, they announced that Windows on ARM – you know, WinRT – would “include” Microsoft Office. What does “include” mean? Is it included in the price, is it ad supported, like Office 2010 Starter? Or will it require an Office 365 subscription in order to use it? Read more

The Second System Effect

Posted by simon on 2012/04/19
Posted in CommentTechnology  | Tagged With: , , , , , , , , , | 2 Comments

Have you ever got to the end of something and thought “you know, if I did that over again, I would do this – and that – and the other differently”?

That, dear reader, is the second system effect. And it is, in my opinion, exactly what RIM are suffering from right now, what Apple suffered from in the 1990s, Microsoft have been there (twice) and it’s what essentially sealed Multics fate before it ever began. Read more