How to write comments?

[qadeer37]

just starting to get into the habit of writing comments. What do think about my comment writing? any suggestions!

Private Sub btnAddUser_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnAddUser.Click
        Dim objUser As User
        'Gets user index from UserList.
        Dim UserIndex As Integer = lstUsers.FindStringExact(txtUserName.Text)
        'Checks that all feilds are filled proper.
        If txtUserName.Text = "" Or txtPassword.Text = "" Then
            MessageBox.Show("Please fill all the feilds properly", "GameZone", MessageBoxButtons.OK, MessageBoxIcon.Error)
            'Checks for whether UserName already exists.
        ElseIf UserIndex >= 0 Then
            MessageBox.Show("User already exists")
            'add user object to the list.
        Else
            objUser = New User(txtUserName.Text, txtPassword.Text)
            objUser.UserList.Add(objUser)
            lstUsers.Items.Add(objUser)

        End If
    End Sub

 

[kulrom]

Well not so bad although i would include Xml documentation comments as well.
This is an article about How to: Create XML Documentation in Visual Basic

 

[JohnH]

            MessageBox...
            'Checks for whether UserName already exists.
        ElseIf UserIndex >= 0 Then

I would change to:

ElseIf UserIndex >= 0 Then 'UserName already exists

same with:

            'add user object to the list.
        Else

I would change to:

        Else 'add user object to the list.

Both because the line above belongs to the preceeding code block IMO, and that's how I read it. For example I start reading the ElseIf block from that line, and the comment then also blends better in as read.

Also, good tip from kulrom there, that is how types and members and parameters are documented in the .Net library, and you can do the same for your own code. These comments show up in code editor (or Object Browser) when you're using your classes, methods etc.

Another comment feature is you can add tasks using comments, for example

'TODO need to fix [I]~this[/I] eventually

Then it will show up in Task List (Comments) and you can doubleclick it to go back to that place in code. How to: Create Task List Comments

 

[roccoman]

i have found that putting my initials and a date in comments when changing code is helpful - if another dev needs to look at it and also the date lets you know how recent the change was made

 

[taurean100]

plus any reference to the 'original' problem is also helpful...because then you know why and how etc