FEM Python coding standard

About the development of the FEM module/workbench.

Moderator: bernd

Post Reply
User avatar
PrzemoF
Veteran
Posts: 3520
Joined: Fri Jul 25, 2014 4:52 pm
Contact:

FEM Python coding standard

Post by PrzemoF »

Edit by Bernd: https://github.com/FreeCAD/FreeCAD/blob ... entions.md
-------------------------------------------------------------------------------

This is a proposal to standardise python code in FEM workbench. Please share your opinions and suggestions. The main goal is to make the code easier to read.

Overview:
1. General rules
2. FreeCAD FEM specific requirements
3. Macro info requirements

Content
1. General rules
The general rule is to follow PEP8 [1] and use flake8 [2] (or anything that allows PEP8 checks) to enforce it. Use common sense if PEP8 doesn't apply
1.1 Use spaces only with 4 spaces for indent
1.2 Naming policy : ClassNames, variable_names_without_capitals and CONSTANTS_USE_CAPITALS, functions_without_capitals
1.3 Function expected to return a value should indicate what is expected, so is_mesh_valid is a good name, but check_mesh is not a good name
1.4 No trailing spaces or empty lines with white space characters allowed. If you refactor code please clean it!
1.5 It's OK to use a short variable name like x or z for a local variable used in one place, but if the variable is used in many places it should have a meaningful name.
1.6 Icon names should use fem- prefix, only small letters and dashes for separation. like fem-add-part or fem-inp-editor. The only exception is preferences-fem.svg which is used for FEM preferences.
1.7 print strings shall use brackets for future compatibility with python3. In general the code should be written in python3 compatible manner unless it doesn't work with python2
1.8 One import per line, no * imports allowed as it makes harder to validate code.

2. FreeCAD specific requirements
2.1 All files should have a licence header (FIXME - add example)
2.2 Line length is not enforced (should we enforce it?) - please use common sense
2.3 All python functions should have doxygen documentation included [3]
2.4 File name should reflect class name, so FemTools.py contains FemTools class
2.5 Class names and file names that are not supposed to be used for scripting should start with underscore like _MyInternalClass
2.6 FEM GUI commands should inherit from FemCommands class. See see/Mod/Fem/_Command* files as examples.

3. Info that should be included in all macros. Requested by macro manager developer microelly2

Code: Select all

__Comment__ = 'Imports and scales an Airfoil in the form of a Draft Wire (DWire) or Basic Spline (BSpline)'
__Web__ = 'http://forum.freecadweb.org/viewtopic.php?f=22&t=5554'
__Wiki__ = "http://www.freecadweb.org/wiki/index.php?title=Macro_Airfoil_Import_%26_Scale'
__Icon__  = '/usr/lib/freecad/Mod/plugins/icons/airfoil.png'
__Help__ = 'Start the macro and follow the instructions'
__Author__ = 'quick61'
__Version__ = '2.1'
__Status__ = 'stable'
__Requires__ = 'freecad 0.14.3706'
__Communication__ = 'your email adress or yourgit or something else'
[1] https://www.python.org/dev/peps/pep-0008/
[2] https://github.com/PyCQA/flake8
[3] https://github.com/FreeCAD/FreeCAD/blob ... ls.py#L100

Footnote: coding rules are to some extent matter of personal preference and as such are always open to discussion. If you don't like those above please provide a good example why they need to be changed, so we can improve them!
Jee-Bee
Veteran
Posts: 2566
Joined: Tue Jun 16, 2015 10:32 am
Location: Netherlands

Re: Python coding standard [WORK IN PROGRESS]

Post by Jee-Bee »

Why only a coding standard for FEM and not for FreeCAD wide??
Last edited by PrzemoF on Thu Oct 15, 2015 1:17 pm, edited 1 time in total.
Reason: Typo in the original topic title
User avatar
PrzemoF
Veteran
Posts: 3520
Joined: Fri Jul 25, 2014 4:52 pm
Contact:

Re: Python coding standard [WORK IN PROGRESS]

Post by PrzemoF »

I'm not a core developer and I'm trying to sneak in something that is convinient for me - that's why! :lol:

But if it's works out well we might ask the core devs to make it official FreeCAD policy.
User avatar
bernd
Veteran
Posts: 12849
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland
Contact:

Re: Python coding standard [WORK IN PROGRESS]

Post by bernd »

Most Developing in FEM is done by Przemo and Me. We already use flake8. Since it seams we get more attraction and more developer for FEM, we now try to apply a coding standard for FEMWB. We should be patient and collect experience. Hey we just have propossed them !!

Ahh I agree with most of them. I'm missing module names of FEM PythonModules and how about flake8's error E701, multiple statements on one line (colon). https://github.com/berndhahnebach/FreeC ... er.py#L685
Jee-Bee
Veteran
Posts: 2566
Joined: Tue Jun 16, 2015 10:32 am
Location: Netherlands

Re: Python coding standard [WORK IN PROGRESS]

Post by Jee-Bee »

Dual language comments... Probably not readeble for everyone
User avatar
PrzemoF
Veteran
Posts: 3520
Joined: Fri Jul 25, 2014 4:52 pm
Contact:

Re: Python coding standad [WORK IN PROGRESS]

Post by PrzemoF »

To be honest I don't like multiple statements in one line, but I can live with that if you want it.

I don't know how we should name python modules except we should use camel style naming. The problem is that I don't want to force a Fem/FEM prefix to avoid creating a monster like FemccxFrdReader.

My proposition:
1. Fem* for general python modules,
2. ccx* for CalculiX related stuff
3. _Command* for GUI commands (underscore suggest internal use only).

Most of FEM python modules match this convention already
User avatar
PrzemoF
Veteran
Posts: 3520
Joined: Fri Jul 25, 2014 4:52 pm
Contact:

Re: Python coding standard [WORK IN PROGRESS]

Post by PrzemoF »

Jee-Bee wrote:
Dual language comments... Probably not readeble for everyone
There is nothing like that in the master, so I guess those are Bernd's debug comments.
User avatar
bernd
Veteran
Posts: 12849
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland
Contact:

Re: Python coding standard [WORK IN PROGRESS]

Post by bernd »

PrzemoF wrote:
Jee-Bee wrote:
Dual language comments... Probably not readeble for everyone
There is nothing like that in the master, so I guess those are Bernd's debug comments.
Ahh yes these are just my debug once and for sure they will not show up in master, but I would swear there have been a few in FEM lately ... Never mind!
User avatar
bernd
Veteran
Posts: 12849
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland
Contact:

Re: Python coding standad [WORK IN PROGRESS]

Post by bernd »

PrzemoF wrote:...
My proposition:
1. Fem* for general python modules,
2. ccx* for CalculiX related stuff
3. _Command* for GUI commands (underscore suggest internal use only).

Most of FEM python modules match this convention already
I'm with you here.

How about Python ui files? Should they be moved together with cpp ui files in a separate directory like the icons ?
User avatar
microelly2
Veteran
Posts: 4688
Joined: Tue Nov 12, 2013 4:06 pm
Contact:

Re: Python coding standard [WORK IN PROGRESS]

Post by microelly2 »

I had some requirements for handling macros and want remember this here
A macro should have at least theese meta information for autogeneration

Code: Select all

__Comment__ = 'Imports and scales an Airfoil in the form of a Draft Wire (DWire) or Basic Spline (BSpline)'
__Web__ = "http://forum.freecadweb.org/viewtopic.php?f=22&t=5554"
__Wiki__ = "http://www.freecadweb.org/wiki/index.php?title=Macro_Airfoil_Import_%26_Scale"
__Icon__  = "/usr/lib/freecad/Mod/plugins/icons/airfoil.png"
__Help__ = "start the macro and follow the instructions"
__Author__ = "quick61"
__Version__ = '2.1'
__Status__ = 'stable'
__Requires__ = 'freecad 0.14.3706'
__Communication__ = 'your email adress or yourgit or something else'
backref: viewtopic.php?f=21&t=10905&start=20#p91086
Post Reply