File Names
Even without correct documentation, we can help ourselves find relevant pieces of code by splitting it up into correctly-named files. The following are suggestions for file-naming schemes under several languages. A few high-level rules are succeeded by language-specific additional considerations.
1. Rules for All Languages
- Use all-lower-case filenames where words are separated by underscores.
Our primary development platform is Linux, where much is accomplished via the command-line. Using underscores (see examples below) and lowercase letters, we increase the readability of our file names (as the eye tends to recognize spaces), and we add space between files in a listing. In addition, not using upper-case means navigation by keyboard is more efficient; we don't need the shift key.
CarHost.xyz -- Bad.
carHost.xyz -- Bad.
carhost.xyz -- Bad.
car_host.xyz -- Good.
- Write file names (and class names) with the more significant words first, and less-significant names at the end of the name.
The same way directories help us organize information, writing filenames per this hierarchical method automatically groups related files in an alphabetical listing. It is also easier to follow this hierarchy when searching for a relevant file.
e.g. Suppose we have a "map" class and a "position on a map" class in some language x. The files should be named 'map.x' and 'map_position.x', and the class names should reflect this.
- Static routines without an enclosing structure should generally be kept in files that share some or all of that routine's name.
A classic example of this is the file main.cxx, containing the main() routine. Avoid putting a routine called make_new_map() in a file called "routines".
2. Rules for C
- C files should use the extensions .h and .c always.
This is common practice, but as C++ files will also be used, it is important to note.
- In general, every .h file should be accompanied by a .c file.
There is a tendency in C programmers to make files with unique names that have no header/implementation complement (a file named routines.c and another named declarations.h). Doing this voids the organizational benefit that good file naming provides us.
At the same time, files like main.c or constants.h are frequently good design decisions. Use your judgement.
3. Rules for C++
- C++ files should use the extensions .hxx and .cxx always.
This is primarily to separate C headers and implementation from C++ headers and implementation. Especially where C and C++ are intermixed, this clarifies some of the additional rules for #include directives.
- C++ classes should be declared and implemented in files of the same name, without any other classes or routines.
This is an easy way to make it extraordinarily easy to locate a class when browsing code. The primary exceptions to this rule are nested classes and helper functions used in implementation. In these cases, the outermost class should in fact be declared alone.
e.g. The MotionPlanner class should be declared in motion_planner.hxx, and implemented in motion_planner.cxx
4. Rules for Python
- Python files should use the extension .py.
This is common practice for python. Compiled python scripts will by default use the extension .pyc, but these should never be in version control.
- Python classes should be written in files of the same name, not containing unrelated routines.
Being mainly a scripting language, the tendency in Python is to accumulate many routines which are not enclosed in a class or structure. Use good judgement on what routines belong in their own file, versus what routines belong in the same file as a class or data structure.
