We bought a calendaring tool from TMSSoftware that we use to schedule events for SQL Saturday. The calendar works great but has an issue that clears out the screen when deleting an event. It's a really weird behavior. I decided that I needed help from the support staff at TMS. I started the email with a couple of screenshots of the error. Then I started pasting in the code example that I used to delete the event and then rebind the calendar control. This is where I had to step back for a second and think about what I was sending them.
Here is the code that handles the delete event from the control:
Protected Sub WebPlanner1_EventDeleting(ByVal sender As Object, ByVal e As TMS.WebPlanner.PlannerEventDeletingEventArgs) Handles WebPlanner1.EventDeleting
Dim pe As PlannerEvent = e.Event
DeleteEvent(pe)
LoadSessions()
LoadWaitList()
End Sub
I looked at this code and said "Wow, I wonder if they will know what those methods (DeleteEvent, LoadSessions and LoadWaitList) do?". My conclusion was no, they probably won't. The last thing I want is another email asking "What does this do?".
After thinking about it for a few minutes this is more like what I should have wrote:
Protected Sub WebPlanner1_EventDeleting(ByVal sender As Object, ByVal e As TMS.WebPlanner.PlannerEventDeletingEventArgs) Handles WebPlanner1.EventDeleting
Dim pe As PlannerEvent = e.Event
DeleteEventFromDatabase(pe)
BindSessionsToCalendarControl()
BindSessionsToWaitlist()
End Sub
To me, the second code example is going to tell the support staff exactly what I'm doing. But the examples don't stop there. Let's look at the actual "LoadSessions (aka BindSessionsToCalendarControl)" method.
Private Sub LoadSessions()
Dim db As New DatabaseMethods
WebPlanner1.Items.Clear()
WebPlanner1.DataSource = db.GetScheduleSessions(GetEventId)
WebPlanner1.DataBind()
End Sub
The problem here is "GetScheduleSessions". What does that return? Is it a collection of objects or a datatable? GetScheduleSessions returns a datatable but you would know by looking at it. Here is what I should have wrote:
Private Sub LoadSessions()
Dim db As New DatabaseMethods
WebPlanner1.Items.Clear()
WebPlanner1.DataSource = db.GetScheduleSessionsDataTable(GetEventId)
WebPlanner1.DataBind()
End Sub
It's those small changes that make your code just a little easier for you and others to understand what the code is doing. How many times have you gone back to your code 6 months later and said to yourself "What the hell does this do?"
I thought that I had given my methods good names. From the standpoint of another human reading the code and being able to understand it without much effort, I failed.
So going forward I will put more effort into making my method names more readable. It's a lesson I learned a while ago when I read code complete but somehow I deviated from my "learnings".