Hi, I've mostly been on the user side regarding APIs so take this with a grain of salt and beware that this is based on my opinion and experience so it's certainly subjective. ;) One aspect that hasn't been mentioned yet is the benefit of expressive and boring module, function and parameter names. This applies to programming in general but can be important for API design as well. Consider this case: a new user has a specific problem and wants to know whether your API contains a function that can solve it. If the user is able to glean the purpose of functions by just looking at their signatures you have just reduced the friction to finding the solution significantly. The user no longer needs to read every docstring to rule out a function. If someone new isn't able to find the solution to his problem manually but has to resort to a page's search field, there may be room to improve the API. This may be obvious to some but I mention this because I feel like code written in the scientific community is often on the terse side with abbreviations everywhere. This applies especially to the implementation itself (maybe it's the mathematical background?) but to a lesser extent to API design too. In both cases readability suffers a lot. This doesn't mean you shouldn't use well known, established abbreviations such as "FFT" but one should avoid them for anything else. I agree with all points raised by Juan below, especially (a). Following already established practices and guidelines in your field is very often an excellent idea. Best regards, Lars On 18/03/2019 09:41, Juan Nunez-Iglesias wrote:
Well, I wouldn't say I'm an expert in API design, and I actually don't consider skan to be particularly well designed (see: those seams I mentioned I figured out as I wrote the docs — they're not fully patched up), but sure, I'll bite. =) Maybe others on the list have ideas.
(a) scikit-image and scikit-learn are both great APIs. I suggest looking at them most closely when designing yours. (b) I fall very deep on the functional side of "functional vs object oriented". This means: - no state; function outputs depend only on their inputs. - use standard objects and classes as much as possible rather than defining your own classes. - don't reuse variable names. (c) when should you reach for classes? Pietro Berkes wrote the pattern very succinctly in a recent lecture of his. If you find yourself writing def f1(x, y, z): ..., def f2(x, y, z): ..., etc, where x, y, and z are always the same bunch of data, then you should probably write a class that contains those three bits. BUT, I would still aim to write functions, as above, rather than methods of the class.
Hope this helps! =)
Juan.
On Sun, Mar 17, 2019, at 12:12 AM, Stefanie Lück wrote:
I am very interested in this question and discussion as well. Maybe we should start a separate thread.
Cheers Stefanie
Am Sa., 16. März 2019, 14:06 hat Yash Sharma <yashrsharma44@gmail.com <mailto:yashrsharma44@gmail.com>> geschrieben:
Hey Juan, Thanks for a descriptive reply! I needed to ask you more points regarding the API design that you followed. Can you share some ideas as to how did you go about designing your API? _______________________________________________ scikit-image mailing list -- scikit-image@python.org <mailto:scikit-image@python.org> To unsubscribe send an email to scikit-image-leave@python.org <mailto:scikit-image-leave@python.org>
_______________________________________________ scikit-image mailing list -- scikit-image@python.org To unsubscribe send an email to scikit-image-leave@python.org
_______________________________________________ scikit-image mailing list -- scikit-image@python.org To unsubscribe send an email to scikit-image-leave@python.org