I’ve noticed something recently, that open source doesn’t always mean that it is a good source.
As open source projects become more popular with the rise of basic programming skills being taught in school systems around the world, one thing is becoming apparently clear. Open Source isn’t always a good source. I’ve seen a few common faux pas in open source, and they drive me bonkers. So here’s a rundown of what many of you may have been doing horribly wrong or a chance for the rest who have been doing it right all along to nod their heads and agree with me.
Now to make this as painless as possible I’ll be using variations a rather simple VB.net code snippet to show my points. See if they make sense for the good and bad examples.
Non-meaningful Variable or Control Names.
Private Sub TextBox1_KeyPress(sender As Object, e As System.Windows.Forms.KeyPressEventArgs) Handles TextBox1.KeyPress
‘Declare Variables
Dim a As Short = 0
Dim b As String
Dim c As Integer
Dim d As Decimal
Dim e As String
Now the above has quite a few issues. It would be valid code to start a subroutine, and the variables names are valid, but what are they for? Giving meaningful names can remove some confusion. Lets take a look at the same short block of code with meaningful names attached to the variables and controls.
Private Sub txtGradeNum_KeyPress(sender As Object, e As System.Windows.Forms.KeyPressEventArgs) Handles txtGradeNum.KeyPress
‘Declare Variables
Dim Count As Short = 0
Dim GradeEntered As String
Dim Loops As Integer
Dim Average As Decimal
Dim Message As String
It looks quite different. We can tell by just looking at it that we’re going to looking at something to do with grade averages. The GradeEntered and Average variables tell us that much, and we find that the KeyPress Event is related to Grades somehow. By adding meaningful names to variable and controls we have demystified a portion of the code and made it that much easier for someoneelse to understand.
Not using Comments Properly.
There is one Comment in the Above, the line that says ” ‘Declare Variables ” but this isn’t complete commentation. Good Coding would have a header, as well as a simple breakdown of each subroutine. Here’s an example of one of my class projects showing how commentation should be handled.
| #Region “Header” |
| ‘Author: Greg Cronk |
| ‘Date: 02/25/2014 |
| ‘Description: This program allows the user to enter 2 strings converts a numeric string into a letter then parses the 2 values out. |
| ‘ |
| ‘Initial Algorithm: |
| ‘ 1. Get Course Name and Numeric Grade from user |
| ‘ 2. Convert numeric grade to a Letter Grade |
| ‘ 3. Display the Course with the Letter Grade in the Output |
| ‘ 4. Store the Course and Letter Grade and append to a Static |
| ‘ |
| ‘Data Requirements: |
| ‘ Input: |
| ‘ Course Name and Numeric Grade |
| ‘ Output: |
| ‘ Words listed by alphabetical order |
| ‘ |
| ‘Formulas: |
| ‘ A >= 90 |
| ‘ B >= 80 |
| ‘ C >= 70 |
| ‘ D >= 60 |
| ‘ Anything below 60 = F |
| ‘ |
| ‘Refine Algorith In Subs as used. |
| #End Region |
| Public Class frmGradeLogger |
| Private Sub btnResults_Click(sender As System.Object, e As System.EventArgs) Handles btnResults.Click |
| ‘If Course Name Text is a number Then |
| ‘ Display message box asking for a non-numeric entry |
| ‘ If Grade Text is a number Then |
| ‘ Select Case for Text |
| ‘ Case Is < 60 |
| ‘ Grade = F |
| ‘ Case 60 to 69.9 Then |
| ‘ Grade = D |
| ‘ Case Is 70 to 79.9 Then |
| ‘ Grade = C |
| ‘ Case Is 80 to 89.9 Then |
| ‘ Grade = B |
| ‘ Case >= 90 Then |
| ‘ Grade = A |
| ‘ End Select |
| ‘ Else |
| ‘ Display message box asking for a Numeric Value |
| ‘ EndIf |
| ‘Else |
| ‘ Course = Course Name Text |
| ‘ Display Course and Grade in Output Label and add New Line |
| ‘ Output Static = Output Label text |
| ‘Declare Varibles. |
| Static CompileGrades As String |
| Dim CourseName As String |
| Dim ltrGrade As String |
| ‘Check or Numeric Only Entry for Course Name |
| If IsNumeric(txtCourse.Text) = False Then |
| CourseName = txtCourse.Text |
| ‘Assign Letter Grades to Numeric Grade Values |
| If IsNumeric(txtGrade.Text) Then ‘Check to assure the Entry is a Numeric value |
| Select Case txtGrade.Text |
| Case Is < 60 |
| ltrGrade = “F” |
| Case 60 To 69.9 |
| ltrGrade = “D” |
| Case 70 To 79.9 |
| ltrGrade = “C” |
| Case 80 To 89.9 |
| ltrGrade = “B” |
| Case Is >= 90 |
| ltrGrade = “A” |
| End Select |
| Else |
| ‘Prompt the User to give a numeric Grade Value |
| Dim TextEntry As String |
| TextEntry = MsgBox(“Please Enter a Numeric Value”) |
| txtGrade.Focus() |
| End If |
| Else |
| ‘Prompt the User to give a Alpha Numeric Title for the Course. |
| Dim NumericEntry As String |
| NumericEntry = MsgBox(“Please Enter The Course Alpha-Numeric Title”) |
| txtCourse.Focus() |
| End If |
| ‘Output the Results and Store the information in the Compiled Data |
| lblOutput.Text = CourseName & ” ” & ltrGrade & CompileGrades |
| CompileGrades = ControlChars.NewLine & lblOutput.Text |
| End Sub |
| Private Sub btnExit_Click(sender As System.Object, e As System.EventArgs) Handles btnExit.Click |
| ‘Close the Window and Release the Used Memory |
| Me.Close() |
| End |
| End Sub |
| End Class |
Everything above that is Green are comments. Using these as a guide you can see what each section of the code is doing even if you are not familiar with that specific language or programming at all.
The Purpose of it all.
Now I do like the idea of Open Source projects. They grant a level of freedom, and an opportunity to learn that close source obviously doesn’t give us. But with the rise of programming in our school systems, a lot of bad habits are forming. Students may be receiving proper instruction, but like so much else from our classroom lives we fail to see the reasoning or need for much of what we learn. So many open source projects are thousands if not tens of thousands of lines of code with never a comment to be seen. Even worse are the lack of use of meaningful names when declaring variables or establishing control names. I’ve been guilty of it myself in the past, it took a bit of getting used to but once I started using proper techniques the re-readability of my code improved greatly.
Starting an open source project is a good thing, but if you really want it to live up to it’s full potential do us all a favor and use good commentation and meaningful control names. Not doing so greatly diminishes the ability of other people to review, update, fork or otherwise modify the code for their own purposes.