uncategorized

Function and Method Naming Standards

After a brief pause, I’m all liquored up and ready to continue with the next post in the Naming Conventions Series. Today I’ll discuss name standards that are used with functions, methods and overloaded constructors. I’ve decided to roll these three together as all, from a naming convention perspective, are the same. Unlike the past two topics that I’ve discussed (Local and Module variables), function, method and overloaded constructor naming conventions have two components. Of course there is the convention for the function or method name itself (non-issue for constructors as they must be the same as the class), but there also is a convention for the naming of parameters. I’m not going to explore the number of options that I did in my past posts as there are only a couple of different methods that are considered to be valid for these scenarios.

Function and Method Names
Function and method names require a greater amount of attention be paid to the context of the name rather than the format that it is written in. From the Practical Guidelines and Best Practices for VB and C# Developers and Framework Design Guidelines book I can offer the following list:

  • Avoid underscores
  • Avoid names longer than 25 characters if exposed publicly
  • Use verb, verb-noun or verb-phrase syntax
  • Maintain a consistent naming convention for methods or functions that perform similar or opposite operations (i.e. If you have an Open method, have a Close method)In addition to these great suggestions you should also put serious consideration into the style of naming for functions or methods. Name functions and methods so that their purposes and, in the case of functions, their expected return values are clearly determinable. I saw a perfect example of this in some code that I rewrote a while back. There was a class that had a function named something like PaymentEvaluation. When I first saw this function I assumed that it would have code in it that evaluated the payment passed as a parameter. Instead what I found was the this function merely established the class it belonged to in an functional state. Rather than worrying about the naming convention for a week, a day or an hour, I would suggest that the time is better spent searching out code smells like this.

PascalCasing
Probably the more common of the two options I’m presenting here is PascalCasing. This convention is often used across all functions and methods no matter if they are publicly or privately declared (both books beside me make this recommendation). Rather than dwell on the finite details of this convention, I’m going to offer two examples and move on.

1
2
3
4
5
6
7
8
9
public bool IsEmployerBankrupt()
{
//some logic
}

public void EvaluateCandidates()
{
//some logic
}

camelCasing
Not as commonly used, but still with a foothold as a standard is the use of camelCasing for function and method names. I personally have never worked with this standard. Here are examples.

1
2
3
4
5
6
7
8
9
public bool isEmployerLiquidating()
{
//some logic
}

public void splitHairs()
{
//some logic
}

Parameter Naming
Like function and method naming, there are two things to keep in mind when creating parameters. Of course you want to ensure that you are adhering to the naming standards set forth on your project, but you also want to consider what syntax you give the parameters. One of the best recommendations (I’m not sure where I saw this) that I’ve seen is that all constructor parameters should be named exactly the same as the properties that they are setting inside the constructor. This leaves little ambiguity as to the purpose of the parameter. Another great recommendation is to not include reserved parameters for future development. Reserve values, whether its for parameters, enums or something else, only serve to clutter and confuse the code space. A great recommendation, from the Framework Design Guildelines book, is to use enums instead of boolean values to increase the readability of the calling code. Take the following function definitions and resulting calls for example.

1
2
3
4
5
6
7
8
9
public void EvaluateJobCandidates(JobCandidate candidate, bool hasInterviewed, bool hasOffer, bool hasExperience, bool canStartImmediately)
{
//some logic
}

public void SomeFunction(JobCandidate candidate)
{
EvaluateJobCandidates(candidate, true, false, true, true);
}

Compared to

1
2
3
4
5
6
7
8
9
public void EvaluateJobCandidates(JobCandidate candidate, InterviewStatus interviewStatus, OfferStatus offerStatus, ExperienceLevel experienceLevel, StartingTimeframe startTimeframe)
{
//some logic
}

public void SomeFunction(JobCandidate candidate)
{
EvaluateJobCandidates(candidate, InterviewStatus.Completed, OfferStatus.NoneMade, ExperienceLevel.Intermediate, StartingTimeframe.TwoWeeks);
}

The second EvaluateJobCandidates method is much easier to read due to the use of enumerated values. In the past I had not thought of this readability issue, but I will now be using enumerations over boolean types almost all of the time.

Rather than make individual comments on PascalCase, camelCase and Hungarian Notation for the naming convention of parameters, I’m going to generally comment about them. As few, some or all of your methods, functions and constructors will be exposed publicly for consumption and use, you should be very concerned about how you expose these values for this is what people will associate with your code or framework. Consistency is very, very important here. If you are naming your classes or enums using a PascalCase (or camelCase for that matter) standard you will probably want to avoid using that standard for the naming of the parameters your function, method or constructor requires. If you look at the following image you can see that the tooltip is quite confusing when both the type and the parameter have the same casing.

My other suggestion is not to use Hungarian Notation for anything that your classes expose publicly. I’ve worked on a project where the Hungarian Notation convention was imposed on the parameters of methods, functions and constructors and it did nothing but clutter the space. Unlike searching for local or module level variables, when you start typing a method, function or constructor you are presented with a handy tooltip (see above) that offers great insight into the types for the different parameters.

My Choice
Although I’m a Hungarian Notation guy, I do limit it to use on private variables only. The standard that I practice here is PascalCase for my method and function naming combined with camelCasing for my parameters.