Like all style guides it is personal preference.
This was the style guide developed internally at Invenia, mostly before I started.
It was an internal document for years before we open sourced it.
I can shed some light on some bits of it.
Note I don’t agree with all of it as the best choice, but generally I value consistency more.
In general it is designed for:
- a large code-base, Invenias code base is over 1M lines of code,
- continously developed for decades (hopefully), outlasting any single employee
- developed by people of widely varying backgrounds, skills and passions (Invenia has all kinds of folks from senior developers programming for decades, to CS interns, to power systems engineers who might barely have coded before starting but have a whole PhD etc etc)
- running in a production systems, where crashing out unintentionally can cost serious money and cause serious indirect harms.
Now do i think it accomplishes these goals well? Yes, it’s decent at them.
But so would almost any style-guide consistently used.
This kinda thing is the reason why companies develop most style-guides, not individual working on hobby projects.
A thing in particular to remember is that it is old, as i mentioned.
It’s not showing it’s age and is still applicable to day, but some of the motivations are a little different.
This has a number of effects.
- Some bits of it are were written when the language worked different. (there used to be parser ambiguities if you didn’t always use semicolons for semperating keyword arguments. Which made a stronger case for always using them.)
- It is much older than automatic code formatting in Julia. This is a huge one. It is designed with manual inspection in mind, and with things that are easy to tell people how to do. Not things that are easy to do programatically. It leaves a lot of things open as value judgements, and is generally written more as a guideline than a rule..
- It’s older than 4K Monitors being affordable
As i said I wasn’t around for most of it being written.
@omus can give more history probably, or @iamed2 or @Rory-Finnegan .
But here is what i understand to be true:
Matching the CONTRIBUTING.md of JuliaLang/julia
Though there have been a lot of discussion about relaxing that.
- Is one tab per nest level really easier to read than vertical alignment?
It’s easier to roll out as practices consistently across contributors. Especially new ones (who might be interns etc with a lot to learn).
It is a simpler operation to describe.
Alignment is harder to describe.
Personally, I would do what BlueStyle does here, but with tabs.
This is the style that looks consistent no matter what you set your tabsize to.
(the other one is indent with tabs, align with spaces, but even more complex to describe)
But I don’t personally decide things.
- Why limit inline comments?
See 1. but yes there have been even more discussion about removing the limit for comments, (also for string literals)
- Is that the best place for function definition closing parenthesis?
Again, it is simplest to decribe.
Indent once whenever you need to break stuff over multiple lines.
(Not indent twice for arges and once for closing brace if it is a function definition args, and once elsewhere)
- When to use
@assertvs.throw(ArgumentError)?
@assert is a common thing across languages.
It is the semantically a comment saying the following is always true, or else the library author screwed up. It happens to be a comment that is automatically verified when it is passed over.
For input argument checking it is not always true – that can happen because the library user screwed up.
In some versions of julia @assert might be silently ignored.
this means if it does happen your program can enter a undefined state.
(which can be really bad. Like old languages which just ignored errors and executed the next line).
- Should blank lines have strict rules?
I have never seen this strictly followed except when line breaks get really excessive.
Note the BlueStyle introduction
When adhering to this style it’s important to realize that these are guidelines and not rules.
- Should Docstrings show a return variable?
The docstring part of style guide I feel like is mostly ignored.
It’s mostly over engineered. And too verbose.