Path Code Style Guide

[vocx]

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

Ha ha ha. Don't worry about it. It's actually not set in stone. Every community calls it in different ways. But I like the explanation that camelCase is different from PascalCase because of the hump.

[vocx]

I personally do not feel too strongly about snake_case local variables...

The snake_case rule is what gives Python its readability. Becausue it's like whitespace in the middle of a sentence.

Thereasonweareabletoread sentences is because of white_space_between_words. Python is agnst shrtning of wrds just to make the line shorter.

[dubstar-04]

Thank you to everyone for your feedback, comments and helpful guidance.

I have shamelessly stolen the Draft workbench coding conventions (I hope you don't mind VOCX) and updated the first few posts.

I hope that this is just the start of the discussion and we can continue to distill a sensible and useful set of conventions.

Thanks,

Dan

[gwicke]

Looks good to me, thanks @dubstar-04!

One question about the bit about automatic formatters. Is the rationale to discourage reformatting of whole files, or is this a concern about the quality of local automatic formatting? Depending on which it is, we might be able to say so more directly, or provide more concrete guidance / configuration for the use of auto-formatters. I believe we all use some amount of auto-formatting, even if it is just auto-indentation, so better to help people use it productively.

Separately, I think we should just check in the flake8 config, so that it is applied consistently without manual intervention: https://flake8.pycqa.org/en/latest/user ... ation.html

Edit: Put up https://github.com/FreeCAD/FreeCAD/pull/3518 with a config matching the recommended flake8 options

[vocx]

I have shamelessly stolen the Draft workbench coding conventions (I hope you don't mind VOCX) and updated the first few posts.

I love it. Consistency is key in a big program like FreeCAD. Currently Fem and Draft have a very similar coding structure, so I like that we share best practices.

[vocx]

...Is the rationale to discourage reformatting of whole files, or is this a concern about the quality of local automatic formatting?...

My problem with code formatters is that it makes people lazy. Like they rely too much on it.

If I want to correct something, I have to go inside the file, and read the code myself. That gives me the opportunity of spotting problems in the code, and actually improve it. Code formatting gives you a false sense of security that you don't need to look at the code any more, "the formatter will take care of it".

It is said that code is read more than it is written. So, every time that you read the code is an opportunity to improve it.

[sliptonic]

Code: Select all

 flake8 --ignore=E226,E266,W503 file.py 

• E226: spaces around arithmetic operators `*`, `/`, `+`, `-`; sometimes we don't need a space.
• E266: only one `#` for comments; we need two `##` for Doxygen documentation.
• W503: break lines before a binary operator like `and` and `or`. The W503 warning will be changed in the future so we can ignore it for now.

E266 and W503 make sense to me. E226 is a mixed bag.

There are good reasons to ignore it but in general the white space around arithmetic operators make sense.

Apparently Guido's own PEP8 guide gave this example which mixes white space and non-white space. This is clearly more readable than either alternative. I'm inclined to include the ignore just so we're consistent with the Draft wb but it really should be decided on a case by case basis.

Code: Select all

hypot2 = x*x + y*y

[vocx]

I'm inclined to include the ignore just so we're consistent with the Draft wb but it really should be decided on a case by case basis.

That's exactly the purpose of ignoring the check.

If you don't ignore it, when you run flake8, this raises a warning.

Code: Select all

hypot2 = x*x + y*y

We don't want to see a warning in this case, we want to handle mathematics ourselves.

I first found this issue when I was cleaning up the WorkingPlane module of Draft, which has a lot of mathematics. It was reporting a lot of spacing errors. So I think when dealing with mathematics, the best is to let the user arrange the code in a way that makes sense, even if not strictly following this spacing rule.

I think this spacing rule applies mostly to equals, plus and minus signs, but multiplication and division often look better when they are next to their operands.

Code: Select all

final = a*b + c/d - e + f

[vanuan]

See my formal proposal: https://github.com/FreeCAD/FreeCAD-Enha ... s/issues/9