h2g2 The Hitchhiker's Guide to the Galaxy: Earth Edition

The most important thing to do with comments, in my viewpoint, is to include comments at the level of entire functions or higher. Knowing what 'a++;' does isn't terribly helpful - knowing what an entire function does is far more useful. Better yet is comments for an entire class, to say what its purpose is.

I'd also reckon that it's very useful to use assertions to confirm that code works as planned. Ideally, you should put assertions at the start of a function to check that the parameters are all valid and make sense, and assertions at the end of a function to check that the answer it's calculated makes sense. That way, you'll find an error sooner rather than later, which is always a good idea.

Yes, there is a strong argument that over commenting can lead to as many problems as under commenting. This is particularly true with code that is being continually maintained, since all too often comments are not updated when the code is. This can lead to a situation where comments are actively missleading since they refer to code that has been changed. Needless to say this i smore likely to happen the more comments you have, especially if they are trivial ones that are annoying to update.

It is true that comments don't get updated by some programmers when they update the code. My contention is that this represents shoddy programming technique.

I agree that commenting the minutae is unneccessary - especially if you use good variable naming convention such that you never have code that reads: a++

Unfortunately not all languages support assertion. For those that do it is definitely a "must do". I think this comes under the "expect the unexpected and deal with it" point.

Putting in tests for seemingly obvious things here and there to make sure, for example, that a pointer isn't computed as zero or negative, are very often useful. These are called 'can't happen errors' because they should never be executed in working code.

See the entry on 'can't happen' in the New Hacker's Dictionary ([URL removed by moderator]).

For heaven's sakes! See link 2 at http://www.bbc.co.uk/h2g2/guide/A523766

Yup - I saw it before it got nuked.

I would refer to this as "bulletproofing" in VB - i.e. for a SetFocus you bullet proof it thus:
Public Sub BulletProofSetFocus(ctrl As Control)

'\\ Only a visible control can get the focus
If ctrl.Visible Then
'\\Only an enabled control can get the focus
If ctrl.Enabled Then
ctrl.SetFocus
End If
End If

End Sub

Visual Basic? Horrible language. It's full of useless and inconsistent syntatic sugar that makes the code very hard-to-maintain. Besides, you can't do low-level stuff with it, which makes it so much less fun.



Besides, your code is incredibly long-winded - you could cut it down to three lines. (I only know that for certain because I'm being forced to use VB at A-level.)

"Bulletproof" is also in the Dictionary, but it's not used as a verb.

Whoops, I forgot we weren't allowed to spit... sorry...

Although I can't post the linke here there is a site which is on my home page and begins with the letter "M" which has VB source code for a whole heap of powerful things - changing the shape of the windows, subclassing the WORDBREAKPROC etc. which might be of interest to you.

There are two things that you should remember regarding getting the code down to 2 lines:
1st, Contractors get paid by the hour and 2nd, one day you're going to have to debug that code when you are hung over.

Bulletproofing isn't in the dictionary, nor is leveraging nor concretising. They are in the I.T.ialect though

"bulletproofing"'s in the hacker's dictionary {available at any good search engine} - which is good enough for me...

I have mixed feelings about VB. On the one hand, I can create toy programs in it in about half the time it would take in java, or a third the time it would take in C++. On the other hand, it seems to have a tendency to degenerate into spagghetti faster than you can say Dolmio.

In the largest program I made in VB (imaginatively named "VGATrek"), I gave up on getting rid of the bugs: just coded hugely defensively so it wouldn't crash or get into an inconsistent state. Seemed to work, too - which, looking back, surprises me.

Then again, I last used VB when it was version 3, in win3.1, and I'm told things have hugely improved since then. I may have to have another play...

By "Dictionary" I meant the Dictionary that I cited earlier, viz. the New Hacker's Dictionary. *Not* an ordinary one.

'Concretizing' sounds like suit speak to me (anything ending in 'ize'...).

I strongly agree with these rules and would expand on point 4: never assume that any data generated outside your program will be correctly formatted. Don't just check the file is there - check that every field contains a legal value.

This is particularly important in GUI programs with user input - an old boss of mine always tested programs written by inexperienced coders by simply pressing the "Enter" key at the startup screen, without entering any data. About one in four would crash immediately.

Time spent writing a procedure library to check input field formats, then convert them into standard forms, is *never* wasted.

GVI