DOC: Add Cython style guideline for DIPY. #1714

jhlegarreta · 2019-01-04T15:29:47Z

Add Cython style guideline for DIPY.

Fixes #583.

jhlegarreta · 2019-01-04T15:31:55Z

A very first draft.

Somme comments:

This looks to me useful:
http://pyne.io/devsguide/style_guide.html#cython-style-guide

Please have your say about them: either that we should incorporate them to the guideline as they are, or that we want to add them with specific changes.

One controversial point may be that of the Pointers & References: the Good syntax is not what C-people would recommend. However, since pointers (and references I guess) are to dwell on a line of their own, I guess it is fair to keep that.

I have not added guidelines related to what @matthew-brett mentioned in Make a cython style guide #583 about

Use of npy_intp for anything holding an index or shape value, when to use the ndarray Cython
syntax compared to the memoryviews compared to simple C arrays, how to use nogil to root out 
Python-side stuff and optimize speed, that kind of thing.

since my experience writing/reading Cython code is limited. So suggestions for content are welcome.

I ignore where the rules or compilation warnings like the one addressed in BUG: Fix Cython one-liner non-trivial type declaration warnings. #1706 stem from, or where we could find the standard so that we can reference it and save listing each and every warning we find in the CI's. I've looked for a while and did not find any related documentation. If anyone happens to know that, please point to the URL.

codecov-io · 2019-01-04T22:18:06Z

Codecov Report

❗ No coverage uploaded for pull request base (master@def59ac). Click here to learn what that means.
The diff coverage is n/a.

@@           Coverage Diff            @@
##             master   #1714   +/-   ##
========================================
  Coverage          ?   84.3%           
========================================
  Files             ?     115           
  Lines             ?   13790           
  Branches          ?    2186           
========================================
  Hits              ?   11625           
  Misses            ?    1656           
  Partials          ?     509

matthew-brett · 2019-01-26T12:06:14Z

Are you proposing to add the style guidelines you pointed to. They seem reasonable.

matthew-brett

A couple of small comments.

doc/devel/coding_style_guideline.rst

jhlegarreta · 2019-01-27T00:51:09Z

Thanks for the suggestions @matthew-brett !

jhlegarreta · 2019-01-27T00:52:59Z

Anyone having the bandwith to comment on the open questions? Thanks.

skoudoro · 2019-02-05T19:39:09Z

Hi @jhlegarreta,

Can you rebase your PR ?

Please have your say about them: either that we should incorporate

I think you can incorporate what you pointed too.

I have not added guidelines related to what....

I will try to create a PR on you repo for this point

I ignore where the rules or compilation warnings like the one addressed in...

I am ok with that point.

@arokem, @Garyfallidis, any thought?

jhlegarreta

a27b8ac rebased on master and added a few more sections to the guideline based on the link I found.

Some comments inline.

I may find to modify the examples using DIPY's Cython specific code, but the guidelines are already there.

Suggestions, contributions are welcome.

jhlegarreta · 2019-02-07T03:12:42Z

doc/devel/coding_style_guideline.rst

+When declaring an error return value with the `except` keyword, use one space on
+both sides of the `except`. If in a function definition, there should be no
+spaces between the error return value and the colon `:`. Avoid `except *`
+unless it is needed for functions returning `void`::


There are a few places where

Avoid `except *` unless it is needed for functions returning `void`:

sentence is not fulfilled in DIPY, e.g. in featurespeed.pyx:53:

cdef void c_extract(Feature self, Data2D datum, Data2D out) nogil except *:

I need to look deeper into this rule...

jhlegarreta · 2019-02-07T03:17:30Z

doc/devel/coding_style_guideline.rst

+
+  # Good
+  <float> i
+  <void *> s


This may be subject to some discussion/is may be a matter of tastes. I guess the line cythonutils.pyx:141

memview._data = <char*> calloc(buffer_size, sizeof(float))

was may be not written following any specific guideline.

I am ok, with this rule, we can update our code on a new PR. Any other thought?

No. I'm OK with it. Yes, we should eventually converge to abide by these rules in our Cython code 📘 .

jhlegarreta · 2019-02-07T03:19:00Z

doc/devel/coding_style_guideline.rst

+
+  # Good
+  cdef int& i
+  cdef char * s


As said earlier in the PR, personally, I find clearer

cdef int &i

or

cdef char *s

but I am aware this may be controversial.

Personnally, I prefer just this:

cdef int& i cdef char* s

I find it clearer because it avoid to mix different type on the same line. I see often this

cdef char *s, k, *p, t

which is confusing (to see 2 declaration types on the same line)

The example you pointed would not be allowed according to the Variable declaration section rules, since pointer variables should dwell on a line of their own 😅 .

Whether the dereference operator goes beside the type or not, as said, is subject to debate. I'd be OK with whatever is decided, would update the PR with it, and would adapt to it in DIPY.

I find that whatever is decided, the Casting rule/example should also abide by it: i.e. <void *> s or <void*> s.

doc/devel/coding_style_guideline.rst

jhlegarreta · 2019-02-08T01:06:36Z

d19163f uses examples directly taken from the DIPY Cython code.

skoudoro

Thanks for the update @jhlegarreta, here some quick comment

doc/devel/coding_style_guideline.rst

skoudoro · 2019-02-08T14:47:31Z

doc/devel/coding_style_guideline.rst

+
+  # Good
+  <float> i
+  <void *> s


I am ok, with this rule, we can update our code on a new PR. Any other thought?

skoudoro · 2019-02-08T14:54:17Z

doc/devel/coding_style_guideline.rst

+
+  # Good
+  cdef int& i
+  cdef char * s


Personnally, I prefer just this:

cdef int& i cdef char* s

I find it clearer because it avoid to mix different type on the same line. I see often this

cdef char *s, k, *p, t

which is confusing (to see 2 declaration types on the same line)

skoudoro · 2019-02-08T14:57:03Z

doc/devel/coding_style_guideline.rst

+When declaring an error return value with the `except` keyword, use one space on
+both sides of the `except`. If in a function definition, there should be no
+spaces between the error return value and the colon `:`. Avoid `except *`
+unless it is needed for functions returning `void`::


I need to look deeper into this rule...

Add Cython style guideline for DIPY. Fixes dipy#583.

jhlegarreta · 2019-03-05T16:35:15Z

Travis CI failures are unrelated:

dipy/workflows/tests/test_reconst_mapmri.py
dipy/workflows/tests/test_align.py

are failing for different reasons unrelated to this topic. I ignore whether these have already been detected.

skoudoro · 2019-03-05T16:50:42Z

Thanks for the rebase @jhlegarreta.

skoudoro · 2019-03-08T18:58:12Z

This is a good first version so I will go ahead and merge it. I will keep #583 open because this guideline needs a bit more work but it can be done on a new PR.

Thank @jhlegarreta for introducing this guideline.

jhlegarreta force-pushed the AddCythonStyleGuide branch from 8eea49e to 118c286 Compare January 4, 2019 16:07

jhlegarreta mentioned this pull request Jan 7, 2019

DOC: Add Imports section on package shorthands recommendations. #1716

Merged

matthew-brett reviewed Jan 26, 2019

View reviewed changes

doc/devel/coding_style_guideline.rst Outdated Show resolved Hide resolved

doc/devel/coding_style_guideline.rst Show resolved Hide resolved

doc/devel/coding_style_guideline.rst Outdated Show resolved Hide resolved

doc/devel/coding_style_guideline.rst Show resolved Hide resolved

jhlegarreta force-pushed the AddCythonStyleGuide branch from 118c286 to 4c13254 Compare January 27, 2019 00:49

jhlegarreta force-pushed the AddCythonStyleGuide branch from 4c13254 to 4f6e11c Compare February 2, 2019 02:33

jhlegarreta force-pushed the AddCythonStyleGuide branch from 4f6e11c to a27b8ac Compare February 7, 2019 03:09

jhlegarreta commented Feb 7, 2019

View reviewed changes

jhlegarreta force-pushed the AddCythonStyleGuide branch from a27b8ac to d19163f Compare February 8, 2019 01:04

skoudoro reviewed Feb 8, 2019

View reviewed changes

jhlegarreta force-pushed the AddCythonStyleGuide branch 2 times, most recently from ff65019 to 2166e44 Compare February 8, 2019 23:06

skoudoro mentioned this pull request Mar 5, 2019

REL: 0.16.0 #1750

Merged

15 tasks

DOC: Add Cython style guideline for DIPY.

176a3e7

Add Cython style guideline for DIPY. Fixes dipy#583.

jhlegarreta force-pushed the AddCythonStyleGuide branch from 2166e44 to 176a3e7 Compare March 5, 2019 13:44

skoudoro merged commit a3e598f into dipy:master Mar 8, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOC: Add Cython style guideline for DIPY. #1714

DOC: Add Cython style guideline for DIPY. #1714

jhlegarreta commented Jan 4, 2019

jhlegarreta commented Jan 4, 2019

codecov-io commented Jan 4, 2019 •

edited

matthew-brett commented Jan 26, 2019

matthew-brett left a comment

jhlegarreta commented Jan 27, 2019

jhlegarreta commented Jan 27, 2019

skoudoro commented Feb 5, 2019

jhlegarreta left a comment

jhlegarreta Feb 7, 2019

skoudoro Feb 8, 2019

jhlegarreta Feb 7, 2019

skoudoro Feb 8, 2019

jhlegarreta Feb 8, 2019

jhlegarreta Feb 7, 2019

skoudoro Feb 8, 2019

jhlegarreta Feb 8, 2019

jhlegarreta commented Feb 8, 2019

skoudoro left a comment

skoudoro Feb 8, 2019

skoudoro Feb 8, 2019

skoudoro Feb 8, 2019

jhlegarreta commented Mar 5, 2019 •

edited

skoudoro commented Mar 5, 2019

skoudoro commented Mar 8, 2019

DOC: Add Cython style guideline for DIPY. #1714

DOC: Add Cython style guideline for DIPY. #1714

Conversation

jhlegarreta commented Jan 4, 2019

jhlegarreta commented Jan 4, 2019

codecov-io commented Jan 4, 2019 • edited

Codecov Report

matthew-brett commented Jan 26, 2019

matthew-brett left a comment

Choose a reason for hiding this comment

jhlegarreta commented Jan 27, 2019

jhlegarreta commented Jan 27, 2019

skoudoro commented Feb 5, 2019

jhlegarreta left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jhlegarreta commented Feb 8, 2019

skoudoro left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jhlegarreta commented Mar 5, 2019 • edited

skoudoro commented Mar 5, 2019

skoudoro commented Mar 8, 2019

codecov-io commented Jan 4, 2019 •

edited

jhlegarreta commented Mar 5, 2019 •

edited