# Writing maintainable julia code?

**URL:** <https://discourse.julialang.org/t/writing-maintainable-julia-code/1286>\
**Category:** Internals & Design\
**Created:** [January 4, 2017, 4:54pm UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286 "2017-01-04T16:54:39Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![lobingera](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lobingera/32/211_2.png) [@lobingera](https://discourse.julialang.org/u/lobingera)\
**Post date:** [January 4, 2017, 4:54pm UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/1 "2017-01-04T16:54:39Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![kristoffer.carlsson](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kristoffer.carlsson/32/22_2.png) [@kristoffer.carlsson](https://discourse.julialang.org/u/kristoffer.carlsson)\
**Post date:** [January 4, 2017, 8:17pm UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/2 "2017-01-04T20:17:51Z")

</div>

> [@lobingera](#):
>
> because the logic in the code how types and functions implement algorithms are not documented or hard to follow or both.

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.

---

<div class="post-metadata">

**Author:** ![ChrisRackauckas](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/chrisrackauckas/32/77_2.png) [@ChrisRackauckas](https://discourse.julialang.org/u/ChrisRackauckas)\
**Post date:** [January 4, 2017, 8:36pm UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/3 "2017-01-04T20:36:50Z")

</div>

> [@kristoffer.carlsson](#):
>
> 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.

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](https://gitter.im/tbreloff/Plots.jl).

> [@lobingera](#):
>
> Are there general ideas to organize a development from the beginning to enable contributions?

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

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [January 5, 2017, 9:05am UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/4 "2017-01-05T09:05:25Z")

</div>

> [@kristoffer.carlsson](#):
>
> 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.

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 `README`s had something along the lines of _User questions? ask on discourse with the `XXX` tag. Contributor questions are welcome as issues._

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [January 5, 2017, 9:07am UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/5 "2017-01-05T09:07:42Z")

</div>

> [@ChrisRackauckas](#):
>
> Have a Gitter channel so there’s easy discussion and feedback that’s not issue related.

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.

---

<div class="post-metadata">

**Author:** ![mkborregaard](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkborregaard/32/556_2.png) [@mkborregaard](https://discourse.julialang.org/u/mkborregaard)\
**Post date:** [January 5, 2017, 9:33am UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/6 "2017-01-05T09:33:05Z")

</div>

> 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 🙂

---

<div class="post-metadata">

**Author:** ![lobingera](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lobingera/32/211_2.png) [@lobingera](https://discourse.julialang.org/u/lobingera)\
**Post date:** [January 5, 2017, 9:58am UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/7 "2017-01-05T09:58:16Z")

</div>

> [@kristoffer.carlsson](#):
>
> 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.

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.

---

<div class="post-metadata">

**Author:** ![lobingera](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lobingera/32/211_2.png) [@lobingera](https://discourse.julialang.org/u/lobingera)\
**Post date:** [January 5, 2017, 10:03am UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/8 "2017-01-05T10:03:18Z")

</div>

> [@ChrisRackauckas](#):
>
> and tell the debugger to step through a complex plot. X code is pretty beautiful and you’ll understand it when you walk through it.

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.

---

<div class="post-metadata">

**Author:** ![ChrisRackauckas](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/chrisrackauckas/32/77_2.png) [@ChrisRackauckas](https://discourse.julialang.org/u/ChrisRackauckas)\
**Post date:** [January 5, 2017, 10:06am UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/9 "2017-01-05T10:06:30Z")

</div>

> [@Tamas\_Papp](#):
>
> Where do I ask questions about the code?

> [@Tamas\_Papp](#):
>
> I find Gitter inconvenient for this: it is great for quick questions

You answered your own question.

> [@Tamas\_Papp](#):
>
> 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.

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:

> <https://github.com/JuliaPlots/Plots.jl/issues/400>
>
> Spurred on by #392 and jheinen/GR.jl#31, Tom and I had a long discussion in the …Gitter about the definitions of "surface" and "mesh". Let me try to summarize it here:
> \- In Tom's view, a surface has an axis where there are no overlaps. For example, a 3D surface is made by points (x,y,z) where each (x,y) has exactly 1 z, i.e. (x,y)-\>z
> \- These trisurf plots require that once specify the triangular mesh whenever the region is not convex. An example is given in #392. 
> \- I was pointing out that one common use for these is in \[finite element methods\](https://en.wikipedia.org/wiki/Finite\_element\_method). There are multiple Julia projects, such as \[DifferentialEquations.jl\](https://github.com/ChrisRackauckas/DifferentialEquations.jl), \[JuliaFEM\](http://www.juliafem.org/), \[EllipticFEM\](https://github.com/gerhardtulzer/EllipticFEM.jl), \[HPFEM\](https://github.com/pjabardo/HPFEM.jl), etc. for finite elements (and many more packages like \[Fenics\](https://fenicsproject.org/) in C/Fortran). In these examples, what's usually plotted is a solution over a mesh. For example, a 2D finite element method uses a trisurf to plot a 2D mesh with 1D solutions (x,y)-\>z, such as the charge density at each point, or the protein concentration at each point.
> \- The common naming scheme then has an issue when going to 4D: in MATLAB a 2D mesh with 1D solution is plotted with trisurf, but a 3D mesh with a 1D solution, though very similar, is plotted with \[tetramesh\](http://www.mathworks.com/help/matlab/ref/tetramesh.html).
> \- There is a difference between the underlying structure and the representation for it. The 2D mesh + 1D solution can be represented as a surface, though other representations such as a heatmap or wireframe are sensible. 
> \- For these reasons, it may be sensible to abstract this away from just "trisurf" to some kind of plotting of meshes.
> \- This doesn't handle all cases of meshes. All of this discusses cases where the number of nodes in a mesh is 1 more than the dimension. For example, a triangle is defined by 3 points, so a 2D mesh can be represented by a matrix with rows \`\[node1 node2 node3\]\` where each node is given by \`(x,y)\`. If one supplies a mesh like this and a value \`z\` for each node, this gives a 3D structure (x,y)-\>z which satisfies Tom's definition of "surface". However, if the nodes themselves are triangles in 3D space (x,y,z), then this is a different kind of mesh where the "exactly 1 z per (x,y)" may not be satisfied (the surface of a sphere).
> 
> What's the most sensible way to organize the plotting of these 3D structures denoted by triangular meshes? I am not set on any definition, just bringing up common uses, previous implementations, and how they relate.

Neither way in isolation is a good solution.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [January 5, 2017, 11:00am UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/10 "2017-01-05T11:00:51Z")

</div>

> [@ChrisRackauckas](#):
>
> You answered your own question.

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.

---

<div class="post-metadata">

**Author:** ![tknopp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tknopp/32/3569_2.png) [@tknopp](https://discourse.julialang.org/u/tknopp)\
**Post date:** [January 5, 2017, 8:17pm UTC](https://discourse.julialang.org/t/writing-maintainable-julia-code/1286/11 "2017-01-05T20:17:48Z")

</div>

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 😉