Class naming convention

[tcojean]

This is a summary of a small discussion which arose during MR #46 but is more general in Ginkgo. The purpose of this Issue is simply to discuss it and collect everyone's opinion on the subject.

Current class naming convention

The current class naming convention for Ginkgo is detailed here and can be summed up as the following (correct me if I'm wrong in any of this post):

• Usual classes follow the function, variable, ..., naming convention, which is class_name.
• Classes with some sort of polymorphic behavior use ClassName

The reason for the distinction is that polymorphic classes should be used with care and are "heavier" in a way (and capital case can be seen as heavy).

Problems

There are some problems though to distinguish what we consider to be polymorphic behavior. We for example have called the array class Array which has executors so it can be seen as polymorphic behavior, but there are no virtual methods and all of them are quite cheap.

I also think this naming convention can tend to be confusing and at the minimum, the convention should be made very clear somewhere in the code. The reason for that is that the convention itself serves as a form of documentation and it's not useful unless that convention is embedded in the documentation: ClassName documents that this class is polymorphic and could imply significant overhead depending on what you do with it or which function you use.

Personal proposition

I also personally like to be able to distinguish classes from functions, variable names, ..., in all cases so I'm in favor of a uniform ClassName convention. In addition, it's true some classes (LinOps for example) are heavily polymorphic and should be used with care. I think we should have a standard way of adding a @warning in the documentation for those classes.

What do you think @ginkgo-project/developers.

[gflegar]

I am fine with making all classes uniform, and forgetting about polymorphic / non polymorphic behavior. However, if we go that way, I am strongly against the CamelCase convention for all classes. There are several reasons:

• Standard C++ types (and libraries like boost) use lower_case. CamelCase is reserved for template parameters. If we used CamelCase for all classes, we would get a non-uniform look of the code (a fictional, but possible example: xstd::conditional_t<NeedComplex<T>::Value, std::complex<T>, T>, opposed to xstd::conditional_t<need_complex<T>::value, std::complex<T>, T>)
• Class names shouldn't be any different than other type names, as C++ does not (in most cases) make a distinction between a class and a non-class type. This would mean that all types should be CamelCase, including enumerations and aliases for builtin types (should we use Float, Double, Int32?).
• In C++ the distinction between a class (alias) and a function is blurry at best. When using generic programming, class templates can behave like functions that operate on types, e.g. gko::remove_complex.

I vote for just using snake_case for all types, functions, and variables (the compiler surely won't allow you to accidentally mistake one for the other), and reserve CamelCase for template parameters.

[tcojean]

I'm OK with using snake_case. If I proposed CamelCase it is mostly because this is what the Google C++ Style Guide proposes: https://google.github.io/styleguide/cppguide.html#Type_Names

[hartwiganzt]

So the Google C++ Style Guide differs from the Standard C++ types ?

[gflegar]

Yes, and this is not the only difference (references vs pointers, and using exceptions are some more examples). Google has their own take on C++, and while I do agree with a lot of their decisions there are some that don't make much sense to me.