Python coding standard

About the development of the FEM module/workbench.
User avatar
PrzemoF
Posts: 1706
Joined: Fri Jul 25, 2014 4:52 pm
Contact:

Python coding standard

Postby PrzemoF » Thu Oct 15, 2015 9:25 am

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
Posts: 615
Joined: Tue Jun 16, 2015 10:32 am
Location: Netherlands

Re: Python coding standard [WORK IN PROGRESS]

Postby Jee-Bee » Thu Oct 15, 2015 10:45 am

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
Posts: 1706
Joined: Fri Jul 25, 2014 4:52 pm
Contact:

Re: Python coding standard [WORK IN PROGRESS]

Postby PrzemoF » Thu Oct 15, 2015 10:49 am

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
Posts: 3871
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland

Re: Python coding standard [WORK IN PROGRESS]

Postby bernd » Thu Oct 15, 2015 12:19 pm

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
Posts: 615
Joined: Tue Jun 16, 2015 10:32 am
Location: Netherlands

Re: Python coding standard [WORK IN PROGRESS]

Postby Jee-Bee » Thu Oct 15, 2015 12:31 pm

bernd wrote:https://github.com/berndhahnebach/FreeCAD_bhb/blob/891070669701f5d1e0aee8cf74682884bc1d3981/src/Mod/Fem/ccxInpWriter.py#L685

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

Re: Python coding standad [WORK IN PROGRESS]

Postby PrzemoF » Thu Oct 15, 2015 12:51 pm

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
Posts: 1706
Joined: Fri Jul 25, 2014 4:52 pm
Contact:

Re: Python coding standard [WORK IN PROGRESS]

Postby PrzemoF » Thu Oct 15, 2015 12:52 pm

Jee-Bee wrote:
bernd wrote:https://github.com/berndhahnebach/FreeCAD_bhb/blob/891070669701f5d1e0aee8cf74682884bc1d3981/src/Mod/Fem/ccxInpWriter.py#L685

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
Posts: 3871
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland

Re: Python coding standard [WORK IN PROGRESS]

Postby bernd » Thu Oct 15, 2015 2:20 pm

PrzemoF wrote:
Jee-Bee wrote:
bernd wrote:https://github.com/berndhahnebach/FreeCAD_bhb/blob/891070669701f5d1e0aee8cf74682884bc1d3981/src/Mod/Fem/ccxInpWriter.py#L685

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
Posts: 3871
Joined: Sun Sep 08, 2013 8:07 pm
Location: Zürich, Switzerland

Re: Python coding standad [WORK IN PROGRESS]

Postby bernd » Thu Oct 15, 2015 2:24 pm

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
Posts: 2362
Joined: Tue Nov 12, 2013 4:06 pm
Contact:

Re: Python coding standard [WORK IN PROGRESS]

Postby microelly2 » Thu Oct 15, 2015 2:36 pm

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