If you can't beat them -- join them

I must admit I kinda agree with Charles Bloom - information is so dispersed these days. Now it seems that in order to follow you not only should read various blogs and news, but there’s lots of useful stuff going on at Twitter. Tried to defend myself from that, but it’s pointless, it really is a valuable source of info. So, from now on you can also find me here. For the time being I use it mostly to follow other users, but I’ll probably ‘post’ there some stuff that doesn’t justify a blog note.

On another topic, interesting (if a little embarassing) follow-up to this note. I don’t like to comment the code when it’s not needed, as every line of comment is one line more to maintain. However, as it turns out, it can be easily taken too far… Here’s piece of code that I wrote maybe two weeks ago:

if (MoveSpeedSqr >= 9.f)
{
    const float MoveSpeed = Sqrt(MoveSpeedSqr);
    const float Ratio = Clamp01((MoveSpeed - 3.f) / 10.f);
    m_RadialBlur_Power = Lerp(0.0f, 0.02f, Ratio);
    ... 

I mention this, because I still remember coding this fragment and thinking to myself: “should I put a comment here? Naah, it’s self-explaining, no need”. Two weeks later it took me a while to understand what does it do exactly (to my defence - there was a global comment a little higher explaining that we set a radial blur power depending on movement speed, just the details were left uncommented). It is a simple piece of code, but you still have to take a break for a moment and analyze it, it’s not immediately obvious how exactly does it work (plus, there’s constant duplication in disguise).

[If speed is >= 3, then convert it to radial blur power. Blur power is a linear function of speed, is 0 for speed == 3 and 1 for speed >= 13]

Old comments

Jim Tilander 2009-08-15 07:47:21

I think I did add the time-lapse view a while ago when I still knew some C# …:) I think I have the feature mapped to ctrl-T in visual studio … use it all the time.

sam 2009-08-13 03:28:05

You can click the NiftyPerforce history icon and then go right-click “Time-lapse view” in the p4 history window. A single button would be great too though.

Rory 2009-08-12 23:34:28

The fact that you even question whether you needed a comment indicates that you probably should do something about that code. Whether you comment or extract an appropriately named function is up to personal preference I suppose. I would have done the latter.
I use a visual studio add-in which lets me access the Perforce Time Lapse view using a shortcut from visual studio. This is really handy sometimes for just the scenario where the comment doesn’t seem to match the code anymore. I think I spoke to Jim Tilander about adding it to NiftyPerforce, but I can’t remember if he did it or not.

cb 2009-08-12 22:40:29

It would be nice if we had better text-editor-source-control integration so that you could click on a comment and say “show me what the code looked like when this comment was written”.
I actually disagree with your whole position on comments, I think they are always good even when they are wrong. It’s just important to have a different mindset about them - don’t read the comment first and assume it describes the code, read the code first, and then refer to the comment if the code is confusing.
Also small comments right inline with the code are great because they’re much easier to maintain and it’s much easier to just read the code when in doubt. Big block comments before the function are garbage.