ADR suggestion, Naming of modules, classes, methods and variables in python

[andped10]

For code consistency use PEP-8 style where the most important conventions are:

Module

Name should always be snake_small_caps (file tree)

• root_folder.first_folder
• Important to use underscore dandy_fine and minus never-ever. Python will give strange errors

Class

Name should be CamelCase for the individual words.

• BestClassEver

If acronym is part of the name it should be ALLCAPS

• SWATCodeIsTheBest

Methods and variables

Public methods and variables should be snake_small_caps.

Private methods and variables should have a leading underscore _private_method

Assume we have initialized an object of the MyClass:

my_obj = MyClass()
my_obj.public_method()
my_obj._private_method()  # A private method should not be used outside of the class
my_obj.public_variable
my_obj._private_variable  # A private variable should not be used outside of the class

[rozyczko]

We need to differentiate the Qt (application) parts and the rest.
For classes/methods based on QObject, we should use the Qt naming style, which differs from the PEP/Python standard.

[andped10]

@rozyczko just to understand.

• We will use PEP throughout all libs and core repos.
• We will use the qt style throughout all app repos.

[rozyczko]

As for explicit getters/setters:
Python is not Java - I don't think we need explicit wrappers for attributes. Property decorators should be doing the job already and the argument of not accessing internal attributes directly can be addressed by being consistent with leading underscores for "private" members. This won't explicitly fail but we will get loud complaints on the ruff stage

[AndrewSazonov]

In the application logic we also have classes that are pure python without using any Qt modules. After a complete style separation, these classes will follow the Qt style and have, for example, the following code:

thisIsTheModel = TheBestSwatModel()
thisIsTheModel.loadDataFromCifFile(fileName)

In the library, on the other hand, the code would look like this:

this_is_the_model = TheBestSWATModel()
this_is_the_model.load_data_from_CIF_file(file_name)

Now imagine you open both files in an editor and modify them as you work on your application because you realise that the library needs to be refactored. That's exactly what I've done from time to time. In this case, you have to be constantly mindful of the coding style when switching between tabs with different code. So personally, I would soon start mixing the style in both files. This actually happened to me when working on EasyDiffraction App, and as a result part of my variable names look like variableName and the other part like variable_name.

And this was happening with me even when classes were inherited from QObject, so I knew it should be Qt style, but still, working inside Python code, unintentionally used Python style from time to time. Thus, if the application repository had pure Python code, there would be even more style mixing.

I also noticed some style mixing in Simon's code. And that too was due to different styles of variable names. So I think this will become a common issue.

[rozyczko]

1. Can we please split the accessors and the acronym naming issues as separate discussions?
2. As for @AndrewSazonov last comment:

I am not sure I understand the issue:
When calling the lib components from the app, we would use pep8 formatted lib/core calls. Those will be very easy to tell they come from the lib/core since they use ObjectName.method_name style.
When calling the app components from the app, we would use the qt style. This, again, will tell us immediately, what part of the code we refer to without the global namespace search
There is never a case where we call the app method from the library, so we won't pollute anything in there.

This assumes we use the Qt style consistently in all App classes even if they don't derive from QObject.

This might not be the best idea though. Maybe it is better to stick to PEP throughout the whole codebase for consistency?

[AndrewSazonov]

I am trying to emphasise another aspect of this problem. I agree that a clear distinction could be made between where to use Python styles or Qt styles. For example, as suggested, in the library or in the application components. And this should work if the developer is focused only on the library or only on the application code. But we will be working on both parts of the code, and sometimes simultaneously. This means that when switching between tabs with different styles in the IDE, one should always keep the current coding style in mind. When I create a new variable, I again need to check if its name should match one style or another. This is not as simple as using one style in the entire codebase and it can lead to a mix of code styles. Furthermore, if you configure your IDE to use, for example, the Python style, you will always get multiple warnings in each file associated with an application where the Qt style is expected. So I suggest using one coding style, say Python, wherever we can. Then the Qt style will only be used when calling Qt built-in methods in *.py files, and for qml and javascript code in *.qml and *.js files.

[rozyczko]

The consensus of the majority is as in the last @AndrewSazonov 's comment above. We are using the PEP-8 style throughout and the Qt style will only be used when calling Qt built-in methods in *.py files, and for qml and javascript code in *.qml and *.js files.