Python codeformating Draft, Arch in the regard of pep8 etc

[yorik]

About import functions not being at the top: The reason is indeed the speed. Most of the Draft and Arch files are loaded at startup, so their commands are immediately available. However, importing all the bulk of heavyweight modules (Part, pivy, qt...) at start would delay startup a lot. Try for example to load the BIM workbench at startup, where it happens (didn't do my homework there yet ), you'll see the difference...

this is a golden rule since FreeCAD inception, do not load Part at module init...

[carlopav]

Any advice on codeformatting Yorik?
I did find very useful this article by @Moult https://sevenstrokes.net/learn-how-write-good-code .
Maybe it is off topic... But it was really helpful to me.

[yorik]

TBH I'm not the right person to ask about code formatting as I write pretty shitty code

My programming guru, a guy called W. Mayer, not sure if you have heard of him, once said: "It doesn't matter how your code is formatted, as long as it is well commented"

I guess that mostly comes down to try to be nice and clear to others when writing code and spare them as much effort as possible..

[bernd]

TBH I'm not the right person to ask about code formatting as I write pretty shitty code

My programming guru, a guy called W. Mayer, not sure if you have heard of him, once said: "It doesn't matter how your code is formatted, as long as it is well commented"

and you need to live in another star to be able to understand all the different formated code. You both guys do live on this other star (which one of the main reasons FreeCAD is what it is) Since I am just a poor programmer I find it very very helpful for understanding the code to have it formated a special way. May be this is even a preference of a poor programmer, he just needs his formated code. Nevermind I am very happy with well formated FEM python code but step by step get used to the Arch and Draft way too.

[bernd]

I did find very useful this article by @Moult https://sevenstrokes.net/learn-how-write-good-code .

thanks for the link. Gave me some nice new input too.

[chrisb]

I did find very useful this article by @Moult https://sevenstrokes.net/learn-how-write-good-code .

thanks for the link. Gave me some nice new input too.
Interesting reading, but I'm absolutely not agreeing with his recommendation concerning comments. I agree that code should be written as if there were no comments, i.e. not relying on the comment to understand the code. But there should always be comments explaining the idea behind the code. I guess that's what he means saying to comment "why" and not "how".

[vocx]

Now that I've added a bunch of docstrings to various files in Draft, there is more complete programming documentation.

For example, the following image is automatically generated by Doxygen, from Draft/WorkingPlane.py. It's not particularly pretty, because Doxygen just shows the text verbatim. But I hope to investigate in the future the use of Sphinx to produce better documentation.

alignToFace_doxygen.png (55.82 KiB) Viewed 1782 times

To compile the documentation, use make DevDoc in the top level of the FreeCAD source tree. See Source documentation for more information.

[yorik]

Excellent job!! Having a better API documentation is a very important point and we are seriously lacking behind! Very happy you're tackling this

[Kunda1]

This is awesome! Thanks @vocx for leaning in hard on this issue. This is a game changer

[carlopav]

+1