My Programming Naming Philosophy

mardkt836bu

Some thoughts I have on the naming of functions, variables, classes, files, and folder. These thoughts do not have anything to do with project/code structure or architecture.

I apply these thoughts to almost every language I program in, but a language can impact what ideas I implement.

Patterns

Name things using a consistent pattern this is the most significant principle I advocate.

Abbreviations

Avoid uncommon abbreviations but consider scoping with standard abbreviations. For example, when prefixing a string function with the standard str do the same for all string functions. However, some type abbreviations might be uncommon like arr to represent arrays; avoid these.

Short Names

My favorite idea to press is to use short names. Visual debut is real. Think about the value proposition of Python and Ruby.

Short names are more scannable for everyone: human and computer.

If you are using complete words, use the shortest semantic version. For example, I like to use “drive” and “files” over “storage” and “volume”. There is nothing more beautiful than to see a list of folders with short names.

Here is a simple example:

Long

Not bad but takes a while to scan through as the list gets longer.

  • application
  • storage
  • public
  • bootstrap
  • configuration

Short

Easy to scan through, conveys the same information, and uses only one abbreviation.

  • app
  • files
  • www
  • boot
  • config

You can almost instantly pick up the folder you are seeking. When a list of folders has many characters, it tends to read more like a blob.

A – CB

If many classes have similar names, append semantics to the name in all instances but a chosen base instance. I call this “append minus chosen base” or a - cb for short.

For example, a model and controller with the same names Models/Post.php and Controllers/Post.php can be confusing. Append semantics to the name as follows Models/Post.php and Controllers/PostController.php. Note, I do not use Models/PostModel.php because I can have the model class as the chosen base.

General Words First

Start with a general word when you need to search for a name often.

For example, $color_blue has been better than $blue_color for me in SCSS. However, PostController has been better than ControllerPost for controllers in PHP because I use a - cb.

This pattern should feel as though you are building a folder tree structure and trying to use the least number of folders possible.

Correct

Fewer folders 4 total. Take the class ProjectsLaravel.php for example.

+ Projects
  - Laravel
  - WordPress
  - Slim

Incorrect

More folders 6 total. Take the class LaravelProjects.php for example.

+ Laravel
  - Projects
+ WordPress
 - Projects
+ Slim
 - Projects

Hungarian notation

Use Hungarian notation only if needed.

If you find yourself reaching for Hungarian notation your function or code might need to be refactored and shortened. “Hungarian notation” is more specific to strongly typed programming languages like C.

You do not see “Hungarian notation” come up in PHP or JavaScript communities for example.

The Great Rebellion hit its peak with the first release of .NET. Microsoft finally started telling people, “Hungarian Notation Is Not Recommended.” There was much rejoicing. I don’t even think they bothered saying why. They just went through the naming guidelines section of the document and wrote, “Do Not Use Hungarian Notation” in every entry.

Joel Spolsky

Key Stokes

Scope your use of CamelCase and snake_case.

One is not better than the other, but I do like using snake_case because I find it easy to read and scan when in code.

In PHP, I scope snake case to variables and functions; I scope camel case to classes, their methods, and attributes. In a perfect world, I feel I would use only snake_case.

Sliding Scale

Use all these ideas together on a sliding scale. At times you must give to one by taking from another. Frameworks and existing code also influence how you name things. I advise you maintain a consistent pattern.

It is necessary to keep a broad perspective in the naming process but to grow you need to land somewhere and write code. You can always adapt and change with new experiences and knowledge.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.