Path Code Style Guide
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Be nice to others! Respect the FreeCAD code of conduct!
Re: Path Code Style Guide
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
Re: Path Code Style Guide
- 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.
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
- Posts: 698
- Joined: Mon Mar 04, 2013 8:41 pm
- Location: Chester, UK
- Contact:
Re: Path Code Style Guide
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
- Veteran
- Posts: 3459
- Joined: Tue Oct 25, 2011 10:46 pm
- Location: Columbia, Missouri
- Contact:
Re: Path Code Style Guide
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.Syres wrote: ↑Tue May 26, 2020 3:02 pm 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
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.
Re: Path Code Style Guide
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.
Re: Path Code Style Guide
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.dubstar-04 wrote: ↑Tue May 26, 2020 12:16 pm Here are the PEP8 styles for comparison:
- Indentation (Tabs / Spaces)
do we have a preference for the number of spaces (4/8)?
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.PEP8 states that 79 is the maximum, I generally ignore this.
Code: Select all
line = ("Some long piece of text that needs "
"to be broken into "
"several lines")
print(line)
Single line imports are better.import FreeCAD
import Draft
No.Are we still maintaining support for python 2 beyond 0.19?
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.Single quotes are concidered more pythonic, PEP8 has no preference.
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')
What?! There is absolutely a Python convention. It's in PEP8.- Naming Convention
There is no python standard afaik.
*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.
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.External Python functions should include the doc comment?
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.
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.- Tools for checking code style / linting
-pylint
-flake8
- pycodestyle
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.
Last edited by vocx on Tue May 26, 2020 7:44 pm, edited 1 time in total.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
- sliptonic
- Veteran
- Posts: 3459
- Joined: Tue Oct 25, 2011 10:46 pm
- Location: Columbia, Missouri
- Contact:
Re: Path Code Style Guide
Clarification:vocx wrote: ↑Tue May 26, 2020 6:23 pm
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.
ThisIsCamelCase
thisIsPascalCase
this_is_snake_case.
Re: Path Code Style Guide
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
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
Re: Path Code Style Guide
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
- Veteran
- Posts: 3459
- Joined: Tue Oct 25, 2011 10:46 pm
- Location: Columbia, Missouri
- Contact:
Re: Path Code Style Guide
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.
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.