Coding guidelines

[m-weigand]

Feature Request

This issue is aimed at discussing if the following items are worth pursuing in the documentation. Please feel free to close if unimportant. Otherwise I will be happy to propose corresponding changes later on.

Having finally found https://github.com/gimli-org/gimli/blob/dev/doc/community/development/guidelines.md, the following questions came up:

• I think this should be directly linked in the contributing.md file in the top level of the repository
• There is no mentioning of any style guide for the code c++ parts of pygimli. Did you follow a specific guideline, or could imagine proposing one?
• Personally, I am a big fan of short lines (80 or 100 characters per line). I think pep8 proposes a soft limit of 80 characters, but maybe a 100 char. limit would be more appropriate? Maybe this could be a soft guideline, which should be followed, but is not necessarily enforced? Conversion could then be done later in drive-by edits.
• Another issue that came up is: Line endings:
  Looking at https://github.com/gimli-org/gimli/blob/dev/.gitattributes it seems that there is a certain preference for windows-based CRLF line endings. If yes, I think this should also be properly embedded into the guidelines linked above.
  One questions would be why certain files (e.g., .cpp/.c files) are left "as is" (see .gitattributes). I would suggest to homogeneously use crlf as the line ending of choice for storing, and conversion to local line endings via .gitattributes.

Whlie I am not yet sure to what extend this is a result of my local (linux-based) checkout, a quick check of the repository shows a very inhomogeneous landscape in terms of line endings (first nr is dos line endings, second one unix line endings, third one mac line endings):

gimli$ find . -name "*.py" -exec dos2unix -i {} \; | tr -s " " | cut -f 1-4 -d " " | numsum -c -x 2,3,4
65377 80866 2
gimli$ find . -name "*.cpp" -exec dos2unix -i {} \; | tr -s " " | cut -f 1-4 -d " " | numsum -c -x 2,3,4
0 26124 0
gimli$ find . -name "*.md" -exec dos2unix -i {} \; | tr -s " " | cut -f 1-4 -d " " | numsum -c -x 2,3,4
3208 632 0

While not really an issue for developing/working with pygimli, I think having clear rules promotes code health.

It seems as if files were commited with different line endings, as evident by git ls-files --eol:

[...]
i/lf    w/lf    attr/text eol=crlf    	pygimli/utils/hankel.py
i/lf    w/lf    attr/text eol=crlf    	pygimli/utils/ipcserver.py
i/lf    w/lf    attr/text eol=crlf    	pygimli/utils/postinversion.py
i/lf    w/crlf  attr/text eol=crlf    	pygimli/utils/sparseMat2Numpy.py
i/lf    w/lf    attr/text eol=crlf    	pygimli/utils/streams.py
i/lf    w/lf    attr/text eol=crlf    	pygimli/utils/units.py
i/lf    w/crlf  attr/text eol=crlf    	pygimli/utils/utils.py
i/lf    w/lf    attr/text eol=crlf    	pygimli/viewer/__init__.py
i/lf    w/lf    attr/text eol=crlf    	pygimli/viewer/mpl/__init__.py
i/lf    w/crlf  attr/text eol=crlf    	pygimli/viewer/mpl/boreholes.py
i/lf    w/crlf  attr/text eol=crlf    	pygimli/viewer/mpl/colorbar.py
i/lf    w/crlf  attr/text eol=crlf    	pygimli/viewer/mpl/dataview.py
i/lf    w/lf    attr/text eol=crlf    	pygimli/viewer/mpl/matrixview.py
i/lf    w/lf    attr/text eol=crl
[...]

[carsten-forty2]

• the guideline is already linked in the dev version https://dev.pygimli.org/community/contribute/#start-making-your-changes . The guideline could probably need some updates maybe.
• There is no style guide for the c++ code yet. Also the style changed a bit over the last 20 years. If you plan contributions to the core, we can think about some guidelines. Its probably not bad to mimic the style how it is now.
• 80 chars per line is good and that's what I try to change if I see to long lines and have time. However, I don't proactively search for long lines to fix. Also we have the .pylintrc with coding style rules which aren't fulfilled retrospective due to time constraints. In the pygimli-2beta branch there is also a successor .ruff.toml, which is a little bit more strictly, but the application have the same constraints .. I try to fix things if my editor points to problems and I have time. I don't want ruff to autofix things, so it will need some time and patients until a good code health.
• We develop on all three big platforms and line endings should be unified by git. I don't know why there are different LF between cpp and py files. I changed the .gitattributes a bit but unsure if there are side effects. Lets see.