search

dask / dask-image

Distributed image processing
http://image.dask.org/en/latest/
BSD 3-Clause "New" or "Revised" License
208 stars 46 forks source link

Coding style conventions/guide #101

Open jni opened 5 years ago

jni commented 5 years ago

We had some discussions on #94 about coding style. @jakirkham suggested we open a specific issue to discuss them.

I have three specific things that I find "inelegant" (yes, I know, it's imprecise) as currently implemented in dask_image.

  1. fully specified imports, e.g. dask.array instead of da, numpy instead of np. Some of these abbreviations are very ingrained in the community and the full specification is surprising to read. (Not to mention annoying to write.)
  2. Code definitions in __init__.py. Again, this is unconventional. scikit-image doesn't use these and still gets a nice API generation from sphinx, so I don't think it's a major hurdle to get sphinx to behave well for a more conventional code structure.
  3. The import name with an underscore in it. ;)

I'll throw a bonus idea in here: we should rename input in all the ndimage functions. It was a bad choice from SciPy, and they're stuck with it, but I don't think dask-image should be bound by it.

Anyway, whatever is decided with the above points, it should probably be codified somewhere, and preferably it should reference the style guides for bigger projects, so that these aren't "just for dask-image" conventions.

GenevieveBuckley commented 5 years ago

To document our decision today, we will use image and label_image as names for arrays passed into dask-image functions.

This is a move away from strict adherence to the scipy API (we don't like using the name input for arrays passed into functions because input is also the name of a python built in command). Choosing image and label_image mirrors scikit-image's decision, and they've put a fair bit of thought into this subject already.