Commenting source code is for amateurs

  • Thread starter Thread starter Marian F.
  • Start date Start date
M

Marian F.

The 12 years old genius function to count english words in a sentence:

' This is my function to count english words in your string
' s is the string with your words to be counted
' Returns an integer as the number of words found
Public Function iCW(ByVal s As String) As Integer
' We start declaring the variable to count words
Dim c As Integer
' This is the variable used in the for next loop
' to check every char in your string s
Dim i As Integer
' Now check all chars in your string s
' Starts with the 1st char, i = 1
' up to last char, s.Length
For i = 1 To s.Length
' check is the char is a space
If Mid(s, i, 1) = " " Then
' if it is a space, increment the word count WordCount
c += 1
' if it is not, then do nothing
End If
' continue to check words until no more
Next
' return the word count, c
' after adding 1 to compensate for the word before the first space
Return c + 1
End Function


The semi-pro solution to count english words in a sentence:

Public Function WordCount(ByVal Text As String) As Long
While InStr(Text, " ") ' remove double spaces
Replace(Text, " ", " ")
End While
If Replace(Text, " ", "") = "" Then Return 0 ' only spaces
Dim WordCount As Long
For i = 1 To Len(Text)
If Mid(s, i, 1) = " " Then WordCount += 1
Next
Return WordCount + 1
End Function

The pro solution is the same as the semi-pro but without comments

MF
 
I thank the pot for calling the kettle black as doing so makes
it perfectly clear that only 'professional' sissies use Visual Basic.
 
Bad news Marian - Pros comment their code.

Maybe you should have commented which version was which, then you wouldn't
have mixed up semi-pro and pro versions in your final statement.
 
Comments and massive documentation are done in professional software
development... if you don't explain what a function does in comments and
documentation how will you remember what it does after writing another 400
functions? most likely you will forget what 80% of them do by that point and
will need some kind of reference.. and when someone else starts working on
your code also in a team they definatly need reference points to look at
such as comments, markers, and documentation to even begin to understand
what is going on in code especially on a massive scale like 100,000+ lines
of code... so saying comments are useless, pointless, or anything else
similar to that is just stupid. people may think they are "1337" just
because they can read code without comments, but if you had a 100 line
function and had no clue what it did uncommented would you want to step
through it line by line to determine exactly what it does, what it effects
and what it may return? I doubt you would want to waste that time.
 
Marian,
The pro solution is the same as the semi-pro but without comments
Click to expand...

What would this solution be?

'
' Function to count words in a string
'
' Parameters:
' input - string containing words to be counted
'
' Returns:
' The number of words in the string
'
Private Shared Function WordCount(ByVal input As String) As Integer
Static regex As New System.Text.RegularExpressions.Regex("\w+")
Return regex.Matches(input).Count
End Function


Alternatively I would consider using String.Split, Strings.Split, or
RegEx.Split to split the input into "words" then count the number of
elements returned, especially if there was other processing to do on the
words. Note in VS.NET 2005 (aka Whidbey, due out later in 2005) The comments
preceding the function would be in XML Documentation format so as to show up
in the Object Browser & intellisense.

Something like:

''' <summary>Function to count words in a string</summary>
''' <param name="input">string containing words to be counted</param>
''' <returns>The number of words in the string</returns>
''' <remarks>
''' Sample function to return the number of words in a string.
''' </remarks>
Private Shared Function WordCount(ByVal input As String) As Integer
...

Hope this helps
Jay
 
Marian,

A comment or a lesson has always to be on the knowledge of the one who reads
it or who get the lessons, learning writing Dutch to a child of 6 is
normally in my country no problem, that will be a different situation in
most other countries in the world.

Making the books will be the same with that, you can not make the books for
people who are learning Dutch on university the same as for kids from 6 in
Holland or Belgium, and you cannot even use those books in Suriname (South
America) for kids in that culture.

That is the same with commenting, there is a difference when you are
commenting for professionals or do that how to learn to write a program. For
the first ones is in my opinion the less commenting the better choice, than
they know there is something special happening when there is a comment

Just my thought,

Cor
 
Commenting is important,
I know Dutch, and here is MY function:

Public Function GetWordCount(ByVal sText As String) As Long
sText = Trim(sText)
While InStr(sText, " ")
Replace(sText, " ", " ")
End While
Return Split(sText, " ").Length 'create array, count elements (words).
End Function

Note that the name of the function will make clear what it does. Less and
easier to understand code, and the complicated (short handed) part is
commented.


Leo Muller
 
Leo said:
Commenting is important,
I know Dutch, and here is MY function:

Public Function GetWordCount(ByVal sText As String) As Long
sText = Trim(sText)
While InStr(sText, " ")
Replace(sText, " ", " ")
End While
Return Split(sText, " ").Length 'create array, count elements (words).
End Function

Note that the name of the function will make clear what it does. Less and
easier to understand code, and the complicated (short handed) part is
commented.
Click to expand...
Agree

MF
 
Jay said:
What would this solution be?
Click to expand...

A Phd solution from someone who is making a deep study of the framework.

The function name, parameter type and return type are enough to know
what does the function do.
'
' Function to count words in a string
'
' Parameters:
' input - string containing words to be counted
'
' Returns:
' The number of words in the string
'
Private Shared Function WordCount(ByVal input As String) As Integer
Static regex As New System.Text.RegularExpressions.Regex("\w+")
Return regex.Matches(input).Count
End Function


Note in VS.NET 2005 (aka Whidbey, due out later in 2005) The comments
preceding the function would be in XML Documentation format so as to show up
in the Object Browser & intellisense.

Something like:

''' <summary>Function to count words in a string</summary>
''' <param name="input">string containing words to be counted</param>
''' <returns>The number of words in the string</returns>
''' <remarks>
''' Sample function to return the number of words in a string.
''' </remarks>
Private Shared Function WordCount(ByVal input As String) As Integer
...
Click to expand...

That's great :)

MF
 
Wow...

If you think that is a PHd solution I would hate to see what kind of CS
background you have...

See PERL.
 
Back
Top