Naming convention for Octave C++ files that contain classes?

In the Octave interpreted language the name of an m-file and the name of the function contained within should match. This makes sense to me. Should we extend that naming convention to C++ files which contain classes?

While I was updating code I found that the file liboctave/numeric/oct-passwd.h contains the class password rather than the class passwd. This doesn’t seem useful to me as file names can be pretty arbitrarily long these days so naming the file oct-password.h would be clearer.

EDIT: I added a recommendation on naming files to the C++ coding guidelines on the Wiki. See C++ style guide - Octave.

Yeah, I think it helps if the file names match the class names.

What about the oct- and lo- prefixes? Those made sense to me at some point, but I’m not sure now.

Just for the record, and those who never had the pleasure of working on such systems, the origin short names is due to an old recommendation from the GNU coding standards. Way back in the olden times when porting software to old Unix systems was possible, some of them had limits of 14 characters for each path component, and of course there was the 8.3 limitation of MS-DOS. But I’m pretty sure those limitations are behind us for good, so I think it’s safe to try to choose better file and class names.

Sometimes it is necessary to use a prefix to avoid pulling in the wrong header file. For example, there is /usr/include/error.h and liboctave/numeric/lo-error.h. But, I don’t know if there was any reason why sometimes oct- was chosen for “OCTave” and sometimes lo- was chosen for “LibOctave”. In libinterp there is also a convention of using a few letters to indicate the module it belongs to such as pt- for “Parse Tree”.

I definitely think we could be more consistent and thus clearer to programmers that come after us. Is there any good convention we can distill from the observations above?

I think it can help avoid confusion for people reading the code, but the -IDIR options we use should avoid the conflict for the compiler. And we install into an .../include/octave directory by default and external .oct files are usually compiled with an appropriate -IDIR option or use filenames of the form <octave/foo.h> in #include directives, so I don’t think we have to be tied to these prefixes forever if we want to change them.

The pt- and ov- prefixes were originally used so that it was easy to group these files together when they were all in the same directory in the source tree. Now that they are in separate directories, we might be able to use better names.

I may have originally used lo- for names that were in liboctave and oct- for things in liboctinterp (not sure why the name of the directory ended up being libinterp instead of liboctinterp…). I’m not sure that it is true for all of them, but some of these files may have migrated from one directory to another over time or we were just sloppy with the conventions.

This works for the compiler, but it is really hard on the programmer. The programmer can’t just read the source code, but now needs to check the build system to determine which header file is being included. Two things to decipher is worse than one.

Is there any sort of system we can impose on this chaos? What do other large projects, like Qt, do?

Internal header files are included with "file.h" and system files with <foo.h>, so there is also that difference.

I also don’t object to having some clue in the filename itself, though we could certainly aim for some better and more consistent conventions.

Other projects also use prefixes. For example, Qt uses things like QWidgetName for public header files and qsomeinternalheader.h for internal header files.

That’s true, that does make that distinction easier.

Another question. We have adopted the convention that the file name should mirror the name of the contained class. So for the file gtk-manager.h should this be renamed to gtk_manager.h? It makes sense to me, but this would mean a fair number of renamings.

I prefer hyphens over underscores, but that’s not possible for symbol names in C++. Changing all the filenames to to use underscores instead of hyphens seems quite disruptive.