Path Code Style Guide

[Syres]

Whether you agree or disagree with the narrator's code structure, he does provide some IMHO good concepts about information to be provided, docs etc and yes you can ignore the specifics relating to Blender but I still found it useful https://www.youtube.com/watch?v=_8KsNVE6KJs

[gwicke]

- Tools for checking code style / linting

I am much in favor of codifying whatever style is decided in configs for popular tools, so that the drudgery of identifying and partly fixing issues can be automated.

Python:

For linting, flake8 is very popular, and I think does a good job for PEP8 consistency. Default settings are very reasonable, IMHO.

For auto-formatting, https://www.kevinpeters.net/auto-formatters-for-python has a decent overview of some options and trade-offs. I personally have used black quite a bit, but more recently switched to yapf, which produces slightly more compact code. The ability to format only selected portions is important for gradual cleanup, and there are good integrations for editors for pretty much all of these tools.

CPP:

For linting, I personally use clangd, which also provides jump-to-definition etc, via the ALE vim plugin. For formatting, clang-format works well.

[dubstar-04]

I am much in favor of codifying whatever style is decided in configs for popular tools, so that the drudgery of identifying and partly fixing issues can be automated.

I was thinking of setting up a git hook to check my work. Something like this:

https://ljvmiranda921.github.io/noteboo ... nd-flake8/

Thanks,

Dan

[sliptonic]

Whether you agree or disagree with the narrator's code structure, he does provide some IMHO good concepts about information to be provided, docs etc and yes you can ignore the specifics relating to Blender but I still found it useful https://www.youtube.com/watch?v=_8KsNVE6KJs

You successfully distracted me for 15 minutes! That 'Roast my plugin' video is really good. I wish he'd do that as a regular series. I'll thank everyone to NOT 'roast' my code.

BTW, I've recommended Jeff Knupp's book 'Idiomatic Python' to a lot of people. Terrible title but really great book. Extremely readable even to python newbies. If you want to improve your python code, this book is a great place to start.

Also from the video, I found the discussion of CuPy interesting. I wonder if there's any place in Path where a GPU dropin replacement for Numpy might be interesting.

[Syres]

I found the discussion of CuPy interesting. I wonder if there's any place in Path where a GPU dropin replacement for Numpy might be interesting.

I'll start a new thread in Open Discussion as it relates to a few core Wbs and I wouldn't want to go over old ground if @Yorik or someone else has spent time on it already.

[vocx]

Here are the PEP8 styles for comparison:
- Indentation (Tabs / Spaces)
do we have a preference for the number of spaces (4/8)?

Four spaces is Python standard. Eight spaces was common in C around 30 years ago. I think in today's world only 50 year old people are conditioned to using 8 spaces, like those who wrote the Linux kernel.

PEP8 states that 79 is the maximum, I generally ignore this.

It is not too hard to keep line lengths short. I do it all the time in Draft. Usually the culprit is strings, messages that are printed. You can encapsulate them in parentheses and break them.

Code: Select all

line = ("Some long piece of text that needs "
        "to be broken into "
        "several lines")
print(line)

Also, if you don't have enough space in 80 characters you probably have too many nested ifs. This should be refactored.

import FreeCAD
import Draft

Single line imports are better.

Are we still maintaining support for python 2 beyond 0.19?

No.

Single quotes are concidered more pythonic, PEP8 has no preference.

I have to disagree. Double quotes are preferred. But it doesn't matter too much. I prefer to keep some sort of internal consistency, as in single quotes for fixed strings, for example, in the GetResources dictionary of commands. The keys are fixed, so using single quotes is fine.

Messages that are printed to the user are normally in double quotes because they are "variable", and could be changed in the future.

Also, it's important to be smart about the quotes; we can use double quotes if we wish to print single quotes, and vice versa; this avoids the backslash to escape quotes.

Code: Select all

print("Some code that uses the 'print' function")  # I prefer this
print('Some code that uses the "print" function')

- Naming Convention
There is no python standard afaik.

What?! There is absolutely a Python convention. It's in PEP8.

*Edited* because of errors

UPPERCASE are constants; snake_case for all variable and function names; PascalCase for classes. This are the basics. Initial underscore is for private entities, _smal_function, _SmallClass.

Essentially, Python heavily favors snake_case, except for classes. Even module names should follow this, meaning that PathSurface.py is not compliant; it should be path_surface.py.

External Python functions should include the doc comment?

All functions and classes should include a docstring. The docstrings can be large, it doesn't have to be short. We should not care about the tooltip that is displayed by FreeCAD's Python console, we should consider that this documentation string is going to be parsed by Doxygen or Sphinx, so it is displayed properly.

Doxygen is not ideal, we should use Sphinx to generate the documentation. Some people have investigated use of Sphinx in the past, but currently nothing concrete has come out of it. Please read on Numpy-style docstrings, which is what we use in Draft.

Actual comments should start with #. Comments should explain what is going on, but it should not be very verbose. If you name your variables and functions with clear names, often this is enough to properly document what is going on without an excessive amount of comments.

- Tools for checking code style / linting
-pylint
-flake8
- pycodestyle

Yes, use flake8. I strongly recommend using something like Spyder editor. It automatically includes pylint and pycodestyle, and thus checks the style as you write. I use Spyder for Draft, and all Python programming. You should try have code that doesn't show any more warnings.

And I dislike complete the automatic code formatters, like black and yapf. The reason is simple, they make you lazy and make you write sloppy code. Why? Because you are thinking, "meh, the formatter will handle it". That's the attitude of C for example. Python is meant to be well understood when you read it. As long as you follow PEP8, and the advice of Spyder, you will get good, consistent code without relying on code formatters.

One thing I've noticed about Path is that many files are many thousands of lines long. This should also be improved. In Draft we have undertaken this big task of re-organizing the code, so we don't want to have files that are more than 500 lines, if possible. In Path you seem to have a lot of files in the single PathScripts directory. I would personally move those that deal with the GUI to their own directory, so you have clear separation of the internal functions and the graphical tools.

Please look at the toplevel directory of Draft. We have added the coding conventions there, which essentially is PEP8. These coding conventions are also essentially the same for FEM. I took the same file and just removed a few things that I thought were not necessary to mention, in order to keep the list of rules short.

[sliptonic]

UPPERCASE are constants; camel_case for all variable and function names; PascalCase for classes. This are the basics. Initial underscore is for private entitities, _smal_function, _SmallClass.

Essentially, Python heavily favors camel_case, except for classes. Even module names should follow this, meaning that PathSurface.py is not compliant; it should be path_surface.py.

Clarification:

ThisIsCamelCase
thisIsPascalCase
this_is_snake_case.

[vocx]

Clarification:

ThisIsCamelCase
thisIsPascalCase
this_is_snake_case.

Yes, I made a mistake above, which I have corrected.

thisIsCamelCase (lower case at the beginning, camels have the hump in the middle not at the beginning)
ThisIsPascalCase (upper case at the beginning, or CapitalCamelCase)
this_is_snake_case

[gwicke]

I personally do not feel too strongly about snake_case local variables / members vs. mixedCase, but will note that the latter is slightly shorter. I also don't think this distinction is the most important to enforce. The UpperCaseClass and ALLCAPSCONST vs. lowerCaseVariableOrMember (or lower_case_variable_or_member, if you will) and whitespace / line length rules are more important, IMHO.

[sliptonic]

I will not confuse camelCase and PascalCase ever again.
I will not confuse camelCase and PascalCase ever again.
I will not confuse camelCase and PascalCase ever again.
I will not confuse camelCase and PascalCase ever again.
I will not confuse camelCase and PascalCase ever again.
I will not confuse camelCase and PascalCase ever again.