Naming standards and consistency

I’m a big proponent of keeping a consistent naming standard, even when crossing languages.

True, capitalization and syntax may change, but the standard should remain. Importantly, I have found that naming should play to the strengths of the operating system.

File Names

For example, on every operating system you can sort files by name (i.e. in Windows Explorer on Windows, Finder on Mac, and so on for Linux, etc.). With this in mind, naming should be used for a few key benefits:

  1. Group similar files
  2. Sort files by age/date

Grouping similar files is an important part of naming. For example, say we have a Users feature. We have a basic add, edit, update, delete and list all capability. In this situation, we want to preface our file names with user so that they are all sorted as a group. A good naming standard would be:

File Name Use
users List all Users
user_add Add a User
user_edit Edit a User
user_delete Delete a User
user_update Update a User

Notice how I did not specify a file name as this standard works well for HTML, CSS, JavaScript and Python files. To support other languages, we can simply tweak our standards to support the other language’s syntax, such as Users.vb, UserAdd.vb, UserEdit.vb and so on for Visual Basic.NET.

The above standard is superior to one where we put the action first, such as edit_user or add_user. If we put the action first, then all ‘edit’ files will be grouped together: edit_user, edit_company, edit_project.

The grouped approach is superior as we usually are working on the Users feature, or the Companies module, etc. By using the grouped approach all of our files are naturally and automatically sorted by the operating system.

HTML, CSS, JavaScript and Python

Similar to file names, functions, classes, styles, etc. should be consistently named throughout an application. For example, if we are creating a basic JSON enabled RESTful Web Service with JQuery and a JS library up front, then it’s a huge help to keep names consistent throughout the application (at all layers).

Building on our file names example above, the python def for adding a User should be:

def user_add(request):

Then in JavaScript our class definition would be for User with a User.add() method to save data to the server via basic CRUD Create operation.

User.add({

    name: ‘Bob’,

    age: ’23’,

})

Next, in HTML, we would have a form with a CSS class name that also fits our pattern:

<form class="user_add">

Summary

Consistent naming allows us to leverage built in operating systems for sorting files and reduces developer overhead. It makes it easier for software engineers at all layers to know what is above and below them in the software stack.

Advertisements

A consistent pattern for CSS element positioning

I spend a lot of time switching between different languages and each has a slightly different pattern for element positioning. This often creates the need to pointlessly look up the rotation pattern for each language, which is no doubt a waste of time. To overcome this, I find that using the default pattern for a language consistently is key.

For example, CSS has a different pattern then XAML. However, by reusing CSS’ default pattern it makes our code easier to quickly scan and eliminates needless Google searches (sorry Google).

In CSS, the generic pattern is:

  1. top
  2. right
  3. bottom
  4. left

For example, if I set the padding on an element, then I can control the padding for each of the 4 items above as:

padding: 1px 2px 3px 4px;

That is:

  1. top = 1px
  2. right = 2px
  3. bottom = 3px
  4. left = 4px

So, when define the margin edge offset for positioned boxes, it is beneficial to follow this same pattern.

For example, if we have a positioned box such as <div class=”my_class”>, then we’ll follow CSS’ default pattern as follows:

<div class=”my_class>

Then in CSS:

.my_class {
    position: absolute;
    top: 0;
    right: 0;
    left: 0;
    bottom: 0;
}

As can be seen above, we specified the 4 margin edge offsets in the same order that CSS uses by default.

The end goal is to improve readability and to maintain consistency in how and where we specify our CSS. In a large web application, this consistency makes it easy to maintain our CSS by ensuring that we can quickly find a property without having to read every line in detail.