Commenting Access Code

1
Commenting Access Code

• How much is enough?

Charlotte Foust Infostat Systems,
Inc. Sacramento, CA Cfoust_at_infostatsystems.com
2
The Comment Spectrum

• Non-existent
• Occasional
• Sparse
• Verbose
• Pseudo Code
• War and Peace

3
Verbose Code
'basMain 'Created by Charlotte Foust 'Contains
the Main sub and routines available to the rest
of the project Option Explicit 'user-defined
type for household income Public Type
HouseholdIncome IDCode As String 5 'holds
ID Income As Currency 'holds household
income Persons As Integer 'holds
number of members End Type 'HouseholdIncome 'publ
ic array to hold data Public gudtSurvey() As
HouseholdIncome 'public constants for
filename Public Const gDATAFILE As String
"Survey.txt" Public Const gDEFAULT As String
"DefaultSurvey.txt"
4
Verbose Code continued
Option Explicit 'module level variables Private
mintCount As Integer 'holds number of
records Private mcurTotalIncome As Currency
'holds total income Private mcurAvg As Currency
'hold average income Private mintBelowCnt As
Integer 'holds number below poverty level Private
mblnNew As Boolean 'holds flag for new
record Private mSurvey As HouseholdIncome 'holds
each type object Private mintIndex() As Integer
'holds array of indexes '
Private Sub cboIDCode_Click() 'created
by Charlotte Foust 'populate the fields for
the selected record Dim intIndex As Integer
'holds array index 'get the index to
use intIndex cboIDCode.ItemData(cboIDCode.Li
stIndex) 'load the rest of the record from
the array txtAnnualIncome.Text
gudtSurvey(intIndex).Income txtMembers.Text
gudtSurvey(intIndex).Persons 'populate
the control tags with the values 'for
validating changes in record cboIDCode.Tag
cboIDCode.Text txtAnnualIncome.Tag
txtAnnualIncome.Text txtMembers.Tag
txtMembers.Text 'fill the mSurvey
variable with values FillType End Sub
'cboIDCode_Click()
5
Uncommented
Private Sub ClickSort(lbl As Label)     Dim
strCaption As String     Dim strOrderBy As
String     Dim strLblName As String     Dim ctl
As Control         On Error GoTo ClickSort_err
        If lbl.Tag ltgt vbNullString Then
        strOrderBy "" lbl.Tag ""
        strLblName lbl.Name                
For Each ctl In Me.Controls             If
ctl.Section acHeader And ctl.ControlType
acLabel And ctl.Tag ltgt vbNullString Then
                strCaption ctl.Caption
                If strLblName ltgt ctl.Name Then
                    Select Case
Right(strCaption, 1)                        
Case "", "v"                            
strCaption Trim(Left(strCaption,
Len(strCaption) - 1))                        
Case Else                             strCaption
Trim(strCaption)                     End
Select                     ctl.Caption
strCaption                 End If            
End If         Next ctl                
strCaption lbl.Caption         Select Case
Right(strCaption, 1)             Case ""
                strOrderBy strOrderBy "
DESC"                 lbl.Caption
Trim(Left(strCaption, Len(strCaption) - 1))
Chr(32) "v"             Case "v"
                strOrderBy strOrderBy " ASC"
                lbl.Caption Trim(Left(strCaptio
n, Len(strCaption) - 1)) Chr(32) ""
            Case Else                
strOrderBy strOrderBy " ASC"                
lbl.Caption Trim(strCaption) Chr(32) ""
        End Select                 Me.OrderBy
strOrderBy         Me.OrderByOn True    
End If End Sub
6
Types of Comments

• Bullet comments above blocks of code
• Header notes author, date, purpose, etc.
• Warnings about problems with the code
• Reminders of things to be done
• Definitions of terms or variables
• Examples/syntax notations
• Usage notes

7
Benefits - Problems

• Easier to locate blocks of code
• Easier to interpret complex code
• Easier to follow program logic

• Lengthier code
• May obscure or mislead
• May not agree with code contents
• Need to be maintained

8
When To Add Them?

• Before coding - pseudocode
• As code is being written
• After a block of code is finished
• After the project is finished
• When the cows come home

9
Where to Add Them?

• In-line
• ties them tightly to single code line
• Above-line
• can explain block of code better
• Above declarations
• less detailed - summary
• In the documentation
• Yeah, right! Never happens.

10
Discussion