Writing maintainable julia code?


#1

I was following a little bit the plotting packages discussion and some the usual claims about package X, Y and Z showed up and the question “Why don’t people just work on this?” (speed, extendability etc.) turned up in my head.

To me it seems we have (in plotting, but in general) packages around, which are clearly single developer because the logic in the code how types and functions implement algorithms are not documented or hard to follow or both.

So.

Are there general ideas to organize a development from the beginning to enable contributions?


#2

Why do you assume this? I don’t think it is true at all. I think a more likely reason is that it is a lot easier and less time consuming to write forum posts than getting your hands dirty and start to actually try to improve things.

Of course, if you write obscure code, for example by using a lot of macros then it can be harder to find contributors. Also, if you are working on something very advanced (like a typical Keno package :P) then that also makes it harder. Otherwise, just writing idiomatic julia code should be fine.


#3

I agree wholeheartedly. In fact, I’d grab a nice cold beer and tell the debugger to step through a complex plot. @tbreloff’s code is pretty beautiful and you’ll understand it when you walk through it. And you can always ask questions in the Gitter channel.

Have a Gitter channel so there’s easy discussion and feedback that’s not issue related.


#4

I think it is sometimes true, for the following reason: people frequently implement a library that is a bit more general than a specific project, but not so much more general that they spend a lot of time refactoring it to a nice framework/API in the initial phase, because of time pressure, or lack of motivation. In due time, some of these projects undergo refactoring and become more organized, but some don’t. I assume this is natural.

My main problem with contributing is usually the following: suppose I decide that I am willing to invest some time to learn my way around a library, so that I can eventually contribute. Where do I ask questions about the code? Most of the time, I open an issue, but I always feel slightly guilty, because there is no real issue, just me asking questions.

It would be great if all READMEs had something along the lines of User questions? ask on discourse with the XXX tag. Contributor questions are welcome as issues.


#5

I find Gitter inconvenient for this: it is great for quick questions, not so much for looking at previous discussion, especially if that happened a while ago. For technical discussions, I like to go back and read about past threads. Also, Gitter is just a single stream of discussion, very difficult to organize information.


#6

For technical discussions, I like to go back and read about past threads.

I think this is exactly what github issues are for, it makes it nice and easy to refer to the discussion when it grows into PRs and stuff. I am sure all feeling of guilt will evaporate once your improvement PRs get merged :slight_smile:


#7

Well, why do you assume, that i assume this? I actually spend some (quite some) time to get my hands dirty and i have first hand experience of the julia speciality of ‘spaghetti type’…

I agree with you, that [quote=“kristoffer.carlsson, post:2, topic:1286”]
idiomatic julia code should be fine
[/quote].

And that general SW structuring tools (i.e. proper naming, comment the ‘why&how’ and not the ‘what’ etc.) apply here should be common sense.


#8

I disagree. If you need to single step code to understand it, there is high propability the code is missing readablity and maintainability. Good and Beautiful code can be understood just by reading the source. Not executing it.


#9

You answered your own question.

Filling up technical discussions and issues with noise is exactly what Gitter is supposed to stop. Having a written record is good, but having everything written down many times makes everything less legible than if there was nothing at all (since it becomes too daunting to get any information out of it).

Note that a lot of issues comes from Gitter discussions. It helps “prune” the issues for Plots.jl really well: most of the issues are succinct and to the point not because they know everything about Plots.jl and its history really well, but because for already fixed issues people were notified, and for vague issues they were honed in on before the issue was opened. That allows for the issues to be concise technical discussions which are good to learn from.

In addition, some issues spawn from Gitter discussions, like this one:

Neither way in isolation is a good solution.


#10

I think you misunderstood; maybe I was not clear. Gitter is like a conversation, but I don’t think a conversation is best for this kind of discussion. I find the interface a distraction, and sometimes I like to think about issues. This is a personal preference, YMMV. I very much prefer the Discourse-based forum.


#11

Gitter is also certainly not a good option for those developers that might not have time to hang 24h in-front of a computer. I sometimes even have the impression that not all Julia devs live in the same time zone :wink: