Writing a function has it’s own challenges, today lets look at one of them I like to call “Who are you” and see if we can come up with an easy way to name our functions so that they are not only memorable but also expressive and self-documenting.
When I write a function, typically I am doing it because I figured that I needed to build something that would either be called many times or has some complex code that needs to be done, and more often then not, I am deep in the middle of a “brain dump” trying to get what is in my head down onto the screen through my slow fingers (at least they are slower then my head). This leads me to usually come up with some very lame and unacceptable functional names like “GetData” or “Calculate” or other garbage names that you can think of. I then have to stop myself and think through some of those constructs to figure out exactly what the function does.
The first thing that I will ask myself when attempting to name a function is, “What is this method going to do?” Simply enough, it can be one of three types, it can be either an action method, a retrieval method or actional retrieval method. What is the difference you might ask and why is it important? If I am expecting to return something it must be named something that describes what it is returning and also named in such a way that it will tell the person in the next office/cubicle what exactly is going to happen. It’s name should be the contract you have with the program. Take this simple function for example.
|
1 2 3 4 5 6 7 8 9 10 11 |
Function XYZ(ByVal CategorySales, ByVal TotalSales) If IsNumeric(CategorySales) And IsNumeric(TotalSales) Then If TotalSales <> 0 Then XYZ = CategorySales / TotalSales Else XYZ = 0 End If Else XYZ = 0 End If End Function |
I left the function name blank at this point so that we could discuss the possibilities without a “tainted” thought. Looking at the code, it verifies that the Category Sales and Total Sales are Numeric values, then it ensures that Total Sales doesn’t equal zero and then calculates the percentage. Since the entire first part is just to ensure that there is no “monkey business” the rest of the sentance becomes the name of the function. Not only does this document exactly what the function does, but it documents exactly what is happening within the function itself (other languages use things like return, which wouldn’t give that little extra boost of moral).
|
1 2 3 4 5 6 7 8 9 10 11 |
Function CalculatePercentageOfTotalSales(ByVal CategorySales, ByVal TotalSales) If IsNumeric(CategorySales) And IsNumeric(TotalSales) Then If TotalSales = 0 Then CalculatePercentageOfTotalSales = CategorySales / TotalSales Else CalculatePercentageOfTotalSales = 0 End If Else CalculatePercentageOfTotalSales = 0 End If End Function |
Now lets try a different one, this one is a Actional-Retrieval.
|
1 2 3 4 5 6 7 8 9 |
Function XYZ(ByVal CustomerContactInformation) CustomerContactID = LookupCustomerContactInformation(CustomerContactInformation) If CustomerContactID Is Nothing then XYZ = CreateCustomerContactInformation(CustomerContactInformation) Else XYZ = CustomerContactID End If End Function |
Assuming that Customer Contact Information is an object, it appears that this will search for the Customer Contact Information, if it doesn’t find it will run the Create Customer Contact Information, that fairly describes to me…
|
1 2 3 4 5 6 7 8 9 |
Function LocateOrCreateCustomerContactID(ByVal CustomerContactInformation) CustomerContactID = LookupCustomerContactInformation(CustomerContactInformation) If CustomerContactID Is Nothing then LocateOrCreateCustomerContactID = CreateCustomerContactInformation(CustomerContactInformation) Else LocateOrCreateCustomerContactID = CustomerContactID End If End Function |
This seems simple enough, how about just an action method?
|
1 2 3 4 5 |
Sub XYZ(ByVal DegreesTemperature) If MaximumTemperature < DegreesTemperature Then MaximumTemperature = DegreesTemperature End If End Sub |
This checks the current Maximum Temperature, if it is less then the parameter Degrees Temperature, it will assign Degrees Temperature to Maximum Temperature, I would go with CheckMaximumTemperature, but that doesn’t really describe it, nor does UpdateMaximumTemperature; however, AssignNewMaximumTemperature does describe what the action is, we are just validating that Maximum Temperature isn’t assigned to a lower value.
|
1 2 3 4 5 |
Sub AssignNewMaximumTemperature(ByVal DegreesTemperature) If MaximumTemperature < DegreesTemperature Then MaximumTemperature = DegreesTemperature End If End Sub |
As we are creating these descriptions, when the function name becomes to long, it becomes more obvious that our function is doing to much and is becoming overloaded and should be refactored (or separated) into different functions, for instance UpdateMaximumTemperatureAndRefreshDisplaySettings is probably not a good function, this should probably be UpdateMaximumTemperature and RefreshDisplaySettingsToMaximumTemperature makes more sense.
Until next time, Happy Coding and may you be blessed!