=========================================================
Tips on Commenting and Code Layout
=========================================================
When helping other programmers solving bugs on the internet, and looking at 3th party source code I couldn't help noticing their lack of comments. Some code didn't feature ANY comments at all. This phenomenon isn't typical for newbies alone. I've even seen medium or pretty good pogrammers show me source about "difficult" subjects (DirectX, AI, Special Fx, ActiveX or whatever) with a full lack of layout and/or comments.
With this article I'm trying to explain how I use comments and layout in my source. To some of you the examples given by me might seem a bit extreme, however I've come to realize this method of working pays of.
I'll use the following piece of code to illustrate my tips and examples:
Public Sub DispMsg(X As Long)
Select Case X
Case 0
If MsgBox("Something strange happened. No layout was found. Exit?", 16 Or 4, "Warning!")
= 6 Then
Unload Me
End If
Case 1
If MsgBox("Something strange happened. No comments were found. Exit?", 16 Or 4,
"Warning!")
= 6 Then
Unload Me
End If
Case 2
MsgBox "Everything was just fine.", 32 Or 0, "Thank God!"
End Select
End Sub
|
|
During this article I'll use several of my tips to clarify this code.
I know some of you will say: "This code is a piece of cake, why change it? I know exactly what it does."
You're right, this code isn't too hard, however you must realize that the same tips and examples can be aplied to DirectX Programming in C++ with one hand tied to your back, after spending lots of time in the local pub, blindfolded.
"Mmm, yeah that's though."
I knew you'd understand: here's my first piece of advice
First Tip: Use your Tab
You should use the tab after or between certain keywords like:
Sub/Function...End Sub/Function
For...Next
Select Case...End Select
If...Then
And similar keywords.
Look at the improvement:
Public Sub DispMsg(X As Long)
Select Case X
Case 0
If MsgBox("Something strange happened. No layout was found. Exit?", 16 Or 4,
"Warning!") = 6 Then
Unload Me
End If
Case 1
If MsgBox("Something strange happened. No comments were found. Exit?", 16
Or 4, "Warning!") = 6 Then
Unload Me
End If
Case 2
MsgBox "Everything was just fine.", 32 Or 0, "Thank God!"
End Select
End Sub
|
|
Second Tip: Use constants.
Never use the plain numbers for stuff like error codes, fruit, wanted people or whatever. Use an enumeration or a set of constants whenever possible. This will not only make your code a lot easier to read, but if Microsoft gets the weird idea to change the value of vbOkOnly (Which is 0 at the time) into 1, you don't have to memorize/change all those numbers again.
Public Const Err_LayOut As Long = 0
Public Const Err_Comments As Long = 1
Public Const Err_None As Long = 2
Public Sub DispMsg(X As Long)
Select Case X
Case Err_LayOut
If MsgBox("Something strange happened. No layout was found. Exit?", vbCritical
Or vbYesNo, "Warning!") = vbYes Then
Unload Me
End If
Case Err_Comments
If MsgBox("Something strange happened. No comments were found. Exit?", vbCritical
Or vbYesNo, "Warning!") = vbYes Then
Unload Me
End If
Case Err_None
MsgBox "Everything was just fine.", vbInformation Or vbOkOnly, "Thank God!"
End Select
End Sub
|
|
Third Tip: Use describing names, and follow Hungarian notation.
for those of you unfamiliar with hungarian notation: it's a coding convention, you can follow it or you can not. Hungarion notation dictates that variables, objects, modules etc. should have a prefix of 3 characters:
Type: Prefix:
Integer int
Long lng
Single sng
Double dbl
Currency cur
String str
Byte byt
Boolean bln
Object obj
Class cls
Module mdl
Form frm
TextBox txt
OptionBox opt
CheckBox
chk ListBox
lst Error Code err
These are only a couple of examples, other prefixes can be found on the internet.
My other comment was to use describing names: "lngCounter" is a lot more describing than "A" or "X"
Our code now looks like this:
Public Const errLayOut As Long = 0
Public Const errComments As Long = 1
Public Const errNone As Long = 2
Public Sub DisplayErrorMessage(lngError As Long)
Select Case lngError
Case errLayOut
If MsgBox("Something strange happened. No layout was found. Exit?",
vbCritical Or vbYesNo, "Warning!") = vbYes Then
Unload Me
End If
Case errComments
If MsgBox("Something strange happened. No comments were found. Exit?",
vbCritical Or
vbYesNo, "Warning!") = vbYes Then
Unload Me
End If
Case errNone
MsgBox "Everything was just fine.", vbInformation Or vbOkOnly, "Thank God!"
End Select
End Sub
|
|
Fourth Tip: Follow coding conventions.
"Coding conventions? I've heared that before..."
You're right: Hungarion Notation is a coding convention, as well as all other ways I've shown you until now to format and structure your code. Here are some more:
-An ErrorCode containing 0 means succes.
-If the succes of a certain subprocedure is evident, make it a function
so it can return error messages to it's calling function or subprocedure
-Add comments before the same keywords you use the tab key with (check tip no. 1)
-Add the date at the top of each function you create/fill with code
-Add warning messages/ todo messages if you come across bugs
I'm sure there are a lot more, and even some I've violated in the code below, if you know one please contact me.
Finally our code looks like this:
'19 August 2001
'
'Author: Tristan Lambert
'
'Description: This module contains a function
'which is totally useless, however
'it demonstrates several coding conventions
'the use of tab, constants, enumerations and other
'tricks to make your program a lot more easy to read
'
'Last Change: Changed value of errNone into 0
'and made sub DisplayErrorMessage a Function so it
'can return error messages to the calling function
'19 August 2001
'Some constants which describe possible errors
Public Const errNone As Long = 0
Public Const errLayOut As Long = 1
Public Const errComments As Long = 2
'---------------------------------------
'19 August 2001
'An enumeration of possible
'results the function
'"DisplayErrorMessage" can return.
Public Enum ResultEnum
idOk = 0 'The function completed succesfully
idExit = 1 'The user wants to exit
idNoExit = 2 'An error occured but the user doesn't want to exit
idInvalid = 3 'The error id was invalid
End Enum
'---------------------------------------
'19 August 2001
'This function displays an error message
'giving feedback to the user.
Public Function DisplayErrorMessage(lngError As Long) As ResultEnum
'Check which error message has to be displayed
Select Case lngError
'A layout error
Case errLayOut
'Ask the user if he wants to exit because of the error
If MsgBox("Something strange happened. No layout was found. Exit?",
vbCritical Or vbYesNo, "Warning!") = vbYes Then
DisplayErrorMessage = idExit
Else
DisplayErrorMessage = idNoExit
End If
'A lack of comment
Case errComments
'Ask the user if he wants to exit because of the error
If MsgBox("Something strange happened. No comments were found. Exit?",
vbCritical Or vbYesNo, "Warning!") = vbYes Then
DisplayErrorMessage = idExit
Else
DisplayErrorMessage = idNoExit
End If
'Thank god! No error at all
Case errNone
MsgBox "Everything was just fine.", vbInformation Or vbOkOnly, "Thank God!"
DisplayErrorMessage = idOk
'An invalid error code was passed to the function.
Case Else
DisplayErrorMessage = idInvalid
End Select
End Sub
|
|
|
