is this too many comments?

[RickyD]

My instructor wants us to make sure we have a good use of comments in our mid term project

am I going a bit over board with my comments?

This is my completed and working code

in real world programming do you guys use a lot of comments?

' Created by Rick Dobbelmann on 3-10-08 for VB.NET Part 1 Midtem Project
' The purpose of this application is for a user to try and guess a random number 
' created by the application. The player receives a rating depending on how many 
' guesses the player needs to guess the correct number

Public Class xMainForm
    ' declare variables
    Dim name As String
    Dim getName As String
    Dim randomNumber As Integer
    Dim guessedNumber As Integer = 0
    Dim guessComplier As Integer
    Dim gameCounter As Integer = 0
    Dim guessCounter As Integer = 0
    Const wayTooLow As String = " - Way too Low, try again"
    Const wayTooHigh As String = " - Way too high, try again"
    Const tooLow As String = " - Too low, try again"
    Const tooHigh As String = " - Too High, try again"
    Dim rating As String
    Dim randomGenerator As New Random
    Dim isConverted As Boolean


    Private Sub xMainForm_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

        ' When the form loads an input box will show asking the user for their name 
        ' if the user doesnt enter a name the default player name will be "Player"
        getName = InputBox("Please enter your name:", "Name Entry!", "Player")
        name = getName.ToString

        ' disable play again button until the game is completed
        Me.xPlayAgainBtn.Enabled = False

        ' display a welcome lable to the user and also display their name. 
        Me.xWelcomeLabel.Text = Me.xWelcomeLabel.Text & " " & name & ","

        ' When the form loads generate a random number between 1 and 100
        Call GenerateRandomNumber()

        ' set the focus to the guessed number text box.
        Call SetFocus()

    End Sub

    Private Sub xExitBtn_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles xExitBtn.Click

        ' when the player exits the game display the players name, the number of games played,
        ' and the average number of guesses per game

        Dim guessAvg As Integer

        ' catch the exception if no games are played, 
        ' handle it by assigning the value of 0 to the guess average variable
        Try
            guessAvg = guessComplier / gameCounter
        Catch ex As Exception
            guessAvg = 0
        End Try

        MessageBox.Show("Thanks for playing " & name & ControlChars.NewLine _
            & "You played " & gameCounter & " games." & ControlChars.NewLine & "You averaged " _
            & guessAvg & " guesses per game", "Your game stats!", MessageBoxButtons.OK, MessageBoxIcon.Information)
        Me.Close()

    End Sub

    ' sub method to generate a random number
    Private Sub GenerateRandomNumber()
        randomNumber = randomGenerator.Next(1, 101)
    End Sub

    Private Sub xGuessBtn_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles xGuessBtn.Click

        ' check and see if the number entered can be converted to an integer
        ' otherwise display an error message
        isConverted = Integer.TryParse(Me.xNumberTxtBox.Text, guessedNumber)

        ' if number can be converted
        If isConverted Then

            ' then if the guessed number is between 1 and 100 
            If guessedNumber > 0 And guessedNumber < 101 Then

                ' convert the number entered into a integer
                guessedNumber = Convert.ToInt16(Me.xNumberTxtBox.Text)

                ' add 1 to the guess counter
                guessCounter = guessCounter + 1

                ' if the user guesses the correct number 
                ' display results in a message box & current game label 
                If guessedNumber = randomNumber Then

                    ' declare variables
                    Dim youGuessed As String = "You guessed "
                    Dim times As String = " times. "
                    Dim cTitle As String = name & "'s " & "rating"
                    Dim tempLabel As String



                    ' add the total guesses to the guess complier
                    guessComplier = guessComplier + guessCounter

                    ' add one to the game counter
                    gameCounter = gameCounter + 1

                    ' display the guess number counter and  the word correct in the current game label
                    Me.xCurrentGameLabel.Text = "Guess: " & guessCounter & " - Correct" & ControlChars.NewLine _
                        & Me.xCurrentGameLabel.Text



                    ' assign a rating message to the rating string variable
                    ' determined by the guess counter
                    If guessCounter <= 3 Then
                        rating = "Great Work! You are a mathematical wizard"
                    ElseIf guessCounter > 3 And guessCounter <= 7 Then
                        rating = "Not too bad! You have some potential"
                    ElseIf guessCounter > 7 Then
                        rating = "What took you so long? Maybe you need some lessons."
                    End If


                    ' display a message box containing the number of guesses 
                    ' and the players rating
                    MessageBox.Show(youGuessed & guessCounter & times & rating, _
                        cTitle, MessageBoxButtons.OK, MessageBoxIcon.Information)



                    ' disable guess button until play agin button is pressed    
                    Me.xGuessBtn.Enabled = False

                    ' enable play agin button
                    Me.xPlayAgainBtn.Enabled = True


                    ' use the tempLabel to store the current text in the all games label
                    ' I use temp labels in the elseIf statements too
                    tempLabel = ControlChars.NewLine & ControlChars.NewLine & Me.xAllGamesLabel.Text

                    ' add the completed games score to the all games label
                    ' include the game number, the random number, 
                    ' the number of guesses and the players rating
                    ' keep the most current guess at the top
                    Me.xAllGamesLabel.Text = "Game number: " & gameCounter & ControlChars.NewLine _
                        & "Random Number: " & randomNumber & ControlChars.NewLine & "Guesses: " & guessCounter _
                        & ControlChars.NewLine & "Rating: " & rating & tempLabel

                    Me.xPlayAgainBtn.Focus()



                    ' if the random number is less then the guessed number 
                    ' and if the user is greater then 10 numbers off
                    ' display a message telling the user they are way too high 
                    ' or if the user is less then 10 numbers from the correct number 
                    ' display a message telling them they are too high.
                    ' keep the most current guess at the top
                ElseIf randomNumber < guessedNumber Then
                    Dim tempLabel As String
                    Dim wayToo As Integer

                    tempLabel = ControlChars.NewLine & Me.xCurrentGameLabel.Text
                    wayToo = guessedNumber - randomNumber
                    If wayToo >= 10 Then
                        Me.xCurrentGameLabel.Text = "Guess: " & guessCounter & wayTooHigh & tempLabel
                        Call SetFocus()
                    ElseIf wayToo < 10 Then
                        Me.xCurrentGameLabel.Text = "Guess: " & guessCounter & tooHigh & tempLabel
                        Call SetFocus()
                    End If




                    ' if the random number is greater then the guessed number 
                    ' and if the player is greater then 10 numbers off
                    ' display a message telling the user they are way too low 
                    ' or if they the user is less then 10 numbers from the correct number 
                    ' display a message telling them they are too low.
                    ' keep the most current guess at the top
                ElseIf randomNumber > guessedNumber Then
                    Dim tempLabel As String
                    Dim wayToo As Integer

                    tempLabel = ControlChars.NewLine & Me.xCurrentGameLabel.Text
                    wayToo = randomNumber - guessedNumber

                    If wayToo >= 10 Then
                        Me.xCurrentGameLabel.Text = "Guess: " & guessCounter & wayTooLow & tempLabel
                        Call SetFocus()
                    ElseIf wayToo < 10 Then
                        Me.xCurrentGameLabel.Text = "Guess: " & guessCounter & tooLow & tempLabel
                        Call SetFocus()
                    End If
                End If



            Else
                ' if the number entered is 0 or the number entered is greater then 100 display an error message
                MessageBox.Show("Please enter a number between 1 and 100", "Entry Error!", _
                    MessageBoxButtons.OK, MessageBoxIcon.Error)
                Call SetFocus()

            End If
        Else
            ' if the numbered entered cannot be converted to a valid integer display an error message
            MessageBox.Show("Please enter a number between 1 and 100", "Entry Error!", _
                MessageBoxButtons.OK, MessageBoxIcon.Error)
            Call SetFocus()
        End If
    End Sub


    Private Sub xPlayAgainBtn_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles xPlayAgainBtn.Click
        Call GenerateRandomNumber()

        ' enable the guess button 
        Me.xGuessBtn.Enabled = True

        ' disable the play agin button until the next game finishes
        Me.xPlayAgainBtn.Enabled = False

        ' reset the guess counter
        guessCounter = 0

        ' reset the current game label and set the focus to the text box
        Me.xCurrentGameLabel.Text = ""
        Call SetFocus()
    End Sub


    ' only allow the numbers 0 - 9 and the back space button to be 
    ' entered in the guess number text box
    Private Sub xNumberTxtBox_KeyPress(ByVal sender As System.Object, ByVal e As System.Windows.Forms.KeyPressEventArgs) Handles xNumberTxtBox.KeyPress
        If (e.KeyChar < "0" OrElse e.KeyChar > "9") _
            AndAlso e.KeyChar <> ControlChars.Back Then
            e.Handled = True
        End If
    End Sub


    ' simple method to set the focus and select all text in the guessed number text box
    Private Sub SetFocus()
        Me.xNumberTxtBox.Focus()
        Me.xNumberTxtBox.SelectAll()
    End Sub


    ' if the user doesnt want to see the current game results 
    ' they can uncheck the current game check box 
    ' and then the current game label will be hidden
    Private Sub DisplayCurrentGame(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles xCurrentResultsChkBox.CheckedChanged
        If Me.xCurrentResultsChkBox.Checked = False Then
            Me.xCurrentGameLabel.Visible = False
        Else
            Me.xCurrentGameLabel.Visible = True
            Call SetFocus()
        End If

    End Sub


    ' if the user doesnt want to see the all of the games they have completed, 
    ' the player can uncheck all games check box and then the 
    ' all games completed label will be hidden
    Private Sub DisplayAllGames(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles xAllResultsChkBox.CheckedChanged
        If Me.xAllResultsChkBox.Checked = False Then
            Me.xAllGamesLabel.Visible = False
        Else
            Me.xAllGamesLabel.Visible = True
            Call SetFocus()
        End If
    End Sub
End Class

[satanorz]

Indeed, my code is green as Hulk

I personally think that your code is well commented, and yeah, it's better this way.. i've seen a lot of medium/big project's that no one can decypher because has 0 comments.

[HanneSThEGreaT]

Good Job Ricky!
If you were one of my students, I'd be happy.

I just have some thoughts:
Try to summarise the keypoints. Meaning, try not to explain every little thing in one paragraph, but, just, say for example, after a statement just give a quick indication of what that line's purpose is. Take this for example :

    Private Sub DisplayAllGames(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles xAllResultsChkBox.CheckedChanged
        If Me.xAllResultsChkBox.Checked = False Then 'Don't want to see all completed games
            Me.xAllGamesLabel.Visible = False 'Hide
        Else 'They want to
            Me.xAllGamesLabel.Visible = True 'Show games
            Call SetFocus() 'Set the focus
        End If
    End Sub

It still gives the same impression, but I suppose it's just a matter of preference. IMHO, as I said, yours is quite good, and if I were your trainer, you would definitely get good marks

Also, are you using VS 2005 ¿
Because you can add summary info for each sub. For example, if you were to enter 3 apostrophes, like :

'''

You'd get a space where you can add that type of info above each of your subs.

Good work!

[JohnW@Wessex]

HanneSThEGreaT
Member With Special Power

Leaps tall buildings in a single bound?
Faster than a speeding bullet?

(I've never seen that tag before)

RickyD
Summary comments before a block of code is good, especially where thealgorithm is not obvious from the code. Try not to go overboard and comment the obvious though.

[HanneSThEGreaT]

Leaps tall buildings in a single bound?
Faster than a speeding bullet?

(I've never seen that tag before)

LOL! In my wildest dreams!

No, seriosuly, when you reach a certain number of posts, you can customise your "Title". I chose that, well, because of too many things to mention

Good answer though!

[MikeVallotton]

Yes, real world, that is what my code typically looks like. I do the same as HannesTheGreat with abbreviating some of the comments, but I usually have 1 comment for every 2-3 lines of code.

Makes it much easier to pick up a year or two later when you don't remember what you were doing.

[bflosabre91]

you never can have too many comments. i wish i would comment like that, but I am already in the habit of not commenting as much as i should. Keep it up and make a habit of good comments. If there really are too many comments, then you can easily get rid of them before your application goes into production so you are def good to go

[dglienna]

It all depends on who will be looking at the code. If it's only me, then I'll comment sparingly. If someone else will see it, then I'll do the same thing, generally. '

[Craig Gemmill]

Assuming you write and "refactor" your code as efficiently as possible (or, at least, pretty well) you can usually write a summary comment at the beginning of each method to explain what's going on inside. Commenting each line is often more confusing and time consuming for the writer and the viewer.

Obviously there will be cases where you do something completely weird (to work around a bug, etc), in which case you'll want to comment that line directly.

Today, take that block of code you have posted and comment it line-by-line. Then make a copy and comment it using summaries instead. Save them in a safe place. Set an appointment in your calendar to review them in 1-2 months.

See which one makes the most sense to you then, and adopt that method moving forward.

[RickyD]

thanks guys for your comments, I feel better now that you guys approve and think I did well.

[RickyD]

Good Job Ricky!


Also, are you using VS 2005 ¿

Good work!

opps forgot to post that I am using vb.net 2005