Naming Conventions

1. Introduction

This is an overview of all the naming conventions at AirQo. In case you want to contribute to this naming convention Wiki, please do not hesitate to reach out accordingly.

2. Naming Conventions

2.1 Databases

The convention is: [source]-[state]-[description]

Each section of the naming convention is explained in the subsections below:

2.1.1 Source

The source can either be external or internal

2.1.2 State

The state can either be raw or processed.

2.1.3 description

This is more information to help in the easy identification of the data it contains. The name can be separated by underscores.

2.1.4 Examples

• Example One

You are requested to store weather forecast data from an external site. This data contains rainfall and humidity measurements. According to the AirQo naming convention, the name can be: External-raw-weather_forecast_wakiwi

2.1.5 More considerations

• Temporary Names

Because we are continually learning new things which require us to create temporary tables, this requires us to have a convention for temporary tables so that teammates can easily identify them. We shall prefix these ones with (#) and limit them in length to 10 characters. Never use spaces, embedded characters or reserved names because they can confuse scripts and procedures.

• Permanent Names

1. When naming a table, try to use a collective name or object class term for the entity if one exists (such as sensor, device, notification or user). But use the singular rather than the plural form where possible. If the name proves inadequate, then the team can build on it. If a data model has been created as part of the design phase, it should be an end product of the work.
2. Do not give a table name the same name as one of its columns.
3. Avoid concatenating two table names together to create a relationship table when there is already a word in the language to describe the relationship. Example: you can user actor instead of EmployeeCustomer.
4. Keep table names short
5. Be consistent in the casing of the names and the use of underscore. Example. Starting a table name with upper case is kind of standard procedure.
6. Avoid redundancy in the names. Example: User_name. Just naming a table as User should be enough. So that calling a column from the table would be something like: User.name and NOT User.User_name NOR User_name.name.

2.2 Git Branches

Create a new topic branch from master using the naming convention [type]-[issue/task-number/name] to help us keep track of your contribution scope. The names should not exceed three words for easy readability. Make sure you use git merge instead of git rebase while updating your feature branch with the master - we just want to ensure that the integration of changes into the master branch is as simple as possible. We shall also have short lived branches.

2.2.1 Examples

• Example One

git checkout -b issue-23
git checkout -b feature-adding-users

2.3 Files

2.3.1 Delimiting Words

Underscores and Spaces may make it harder to find a file. Removing them reduces the length of the file name, but by using capital letters to differentiate between the words the file name is still readily recognisable. Where capitalised acronyms are used in file names, the acronym should appear in capitals and the first letter of the following word should also be capitalised.

2.3.2 Short file names

Long file names mean long file paths and long URLs which increase the likelihood of error, are more difficult to remember and recognise. Some words add length to a file name but do not contribute towards the meaning, for example words like “the”, “a”, and “and”. Where the remaining file name is still meaningful within the context of the file directory these elements can be removed.

2.3.3 Using Dates in file names

Giving the dates back to front means that the chronological order of the records is maintained when the file names are listed in the file directory. This helps when trying to retrieve the latest dated record

2.3.4 Ordering of elements

The elements to be included in a file name should be ordered according to the way in which the record will be retrieved during the course of every day business. For example, if the records are retrieved according to their date, the date element should appear first. If the records are retrieved according to their description, the description element should appear first.

2.3.5 Version numbers

Where applicable, version number must always appear in file names. To maintain the numeric order when file names include numbers it is important to include the zero for numbers 0-9. This helps to retrieve the latest record number. i.e. 01, 02 … 99, unless it is a year or another number with more than two digits.

2.3.6 Meaningful names

Folder names should indicate the folder’s contents and reflect the functions, activities and transactions that you carry out. Avoid using team names as the basis for folder names as your organisational structure may change; and, vague names like Misc.

2.3.7 More considerations

• Even if your operating system allows you, don't save files containing these characters * : \ / < > | " ? [ ] ; = + & £ $ . You may encounter difficulties searching for or opening them so they are best avoided.
• Don't use initials, abbreviations and codes that are not commonly understood.
• Avoid using common words such as ‘draft’ or ‘letter’ at the start of file names, unless doing so will make it easier to retrieve the record.
• Avoid unnecessary repetition and redundancy in file names and file paths

2.3.8 Reference Notes

• Probably the best file naming convention ever