# Adopt the SciML Style Guide for Julia Base and Standard Library?

**URL:** <https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845>\
**Category:** General Usage\
**Tags:** documentation, sciml, style\
**Created:** [January 2, 2026, 7:05pm UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845 "2026-01-02T19:05:04Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [January 2, 2026, 7:05pm UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/1 "2026-01-02T19:05:04Z")

</div>

After thinking about docstrings from [another post](https://discourse.julialang.org/t/how-do-you-actually-find-out-how-to-use-an-interface-in-julia-like-the-concept-of-iterator-end/134796/23), I was wondering if the [Julia Style Guide](https://docs.julialang.org/en/v1/manual/style-guide/), particularly for `Core`, `Base`, and the standard libraries should be further specified, particularly for docstrings.

Perhaps a good place to start would be the [SciML Style Guide](https://github.com/SciML/SciMLStyle). I’m particularly interested a more [detailed convention for documentation](https://docs.sciml.ai/SciMLStyle/stable/#Documentation). For example, should exported or public `Base` functions follow the example below taken from SciMLStyle?

```julia-auto
"""
    mysearch(array::MyArray{T}, val::T; verbose = true) where {T} -> Int

Searches the `array` for the `val`. For some reason we don't want to use Julia's
builtin search :)

# Arguments
- `array::MyArray{T}`: the array to search
- `val::T`: the value to search for

# Keywords
- `verbose::Bool = true`: print out progress details

# Returns
- `Int`: the index where `val` is located in the `array`

# Throws
- `NotFoundError`: I guess we could throw an error if `val` isn't found.
"""
function mysearch(array::AbstractArray{T}, val::T) where {T}
    ...
end

```

The one thing I might add here would be a `Implements` or `Interfaces` section.

---

<div class="post-metadata">

**Author:** ![apo383](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/apo383/32/11272_2.png) [@apo383](https://discourse.julialang.org/u/apo383)\
**Post date:** [January 2, 2026, 9:18pm UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/2 "2026-01-02T21:18:39Z")

</div>

The answer is YES. Early on, I believe the Julia devs were conservative and didn’t want to be overly prescriptive. The language has clearly matured, and the inconsistencies in docstrings and documentation now outweigh the theoretical pain from over-prescription.

It’s fine to be opinionated at this point, and to have guidelines for core/base. Likely there may be bits deep in the repo that’ll take years or never get updated, and that’s fine. But might as well standardize from now on and set an example for all to follow.

SciML has done a great job of leading the way. AFAIK there haven’t been any revolts. I would go as far as to _recommend_ similar guidelines for _all_ users. I often suffer pangs of doubt “am I doing this the right way?” that are not resolved by websearch. It’s okay to state an opinion without it sounding like Zen of Python. And eventually maybe even adopt the SciML guidelines on interfaces…

---

<div class="post-metadata">

**Author:** ![langestefan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/langestefan/32/207923_2.png) [@langestefan](https://discourse.julialang.org/u/langestefan)\
**Post date:** [January 2, 2026, 9:30pm UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/3 "2026-01-02T21:30:30Z")

</div>

100% agree.

On top of that I would like this to hook into Documenter.jl, so it can read the docstring and nicely format it for me when rendering the docs. Python docs usually do this and it looks much cleaner in my opinion.

 ![image](https://global.discourse-cdn.com/julialang/original/3X/f/2/f2586ac95eba24a36bac36ad073a6575bccd4a72.jpeg)

---

<div class="post-metadata">

**Author:** ![adienes](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/adienes/32/37459_2.png) [@adienes](https://discourse.julialang.org/u/adienes)\
**Post date:** [January 2, 2026, 9:42pm UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/4 "2026-01-02T21:42:36Z")

</div>

I think there are many good points in the SciML style guide, but I do not agree with this one in particular:

> Prefer to not shadow functions

> Two functions can have the same name in Julia by having different namespaces. For example, `X.f` and `Y.f` can be two different functions, with different dispatches, but the same name. This should be avoided whenever possible

in my view, trying to consolidate kinda-similar-kinda-not-really-the-same methods into the same function often leads to a whole lot of bugs that could be avoided if we were more willing to namespace functions per package!

---

<div class="post-metadata">

**Author:** ![apo383](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/apo383/32/11272_2.png) [@apo383](https://discourse.julialang.org/u/apo383)\
**Post date:** [January 2, 2026, 10:23pm UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/5 "2026-01-02T22:23:07Z")

</div>

> [@adienes](#):
>
> [SciML:] Two functions can have the same name in Julia by having different namespaces… This should be avoided whenever possible

I suspect that is mis-worded. SciML has overloaded `solve` everywhere, so do they intentionally re-use method names for a general concept. I believe they mean a couple things: Don’t use the same name for very different concepts, and perhaps don’t use a highly ambiguous or unhelpful name. And of course we can always use the module as a namespace, or `import` to be more explicit.

---

<div class="post-metadata">

**Author:** ![csvance](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/csvance/32/218927_2.png) [@csvance](https://discourse.julialang.org/u/csvance)\
**Post date:** [January 3, 2026, 2:28am UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/6 "2026-01-03T02:28:16Z")

</div>

This is one of the things I noticed the most coming from Python. I’m not sure if its just because I have not dug deep enough in Documenter.jl or not, but at a surface level I didn’t notice a way to neatly document arguments and return types following the Documenter.jl guide. I really like the SciML style and it would be great to see it rendered like this into the generated documentation. It would also be good to see an example of a more complicated docstring make its way into the guide as well. When I first read it I wanted to know how to handle arguments and returned types but just assumed that wasn’t the norm in Julia.

---

<div class="post-metadata">

**Author:** ![jakobjpeters](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jakobjpeters/32/207797_2.png) [@jakobjpeters](https://discourse.julialang.org/u/jakobjpeters)\
**Post date:** [January 3, 2026, 3:50am UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/7 "2026-01-03T03:50:28Z")

</div>

I strongly prefer SciML’s [naming principles](https://docs.sciml.ai/SciMLStyle/stable/#General-Naming-Principles). The style `awordandanotherword` or even worse `abbrvwrd` are quite unnecessary in a world with tab-compilation.

---

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [January 3, 2026, 12:48pm UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/8 "2026-01-03T12:48:08Z")

</div>

> [@adienes](#):
>
> in my view, trying to consolidate kinda-similar-kinda-not-really-the-same methods into the same function often leads to a whole lot of bugs that could be avoided if we were more willing to namespace functions per package!

The main criteria I have here is whether the methods follow a common functional interface or not. If `X.f` always takes two arguments and `Y.f` always takes three arguments, it seems questionable if these are really methods of the same function. That’s very simplified. It really depends on type abstractions and if varargs are part of the interface.

---

<div class="post-metadata">

**Author:** ![langestefan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/langestefan/32/207923_2.png) [@langestefan](https://discourse.julialang.org/u/langestefan)\
**Post date:** [January 3, 2026, 1:50pm UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/9 "2026-01-03T13:50:30Z")

</div>

> [@csvance](#):
>
> I’m not sure if its just because I have not dug deep enough in [Documenter.jl](https://juliaregistries.github.io/General/packages/redirect_to_repo/Documenter) or not, but at a surface level I didn’t notice a way to neatly document arguments and return types following the [Documenter.jl](https://juliaregistries.github.io/General/packages/redirect_to_repo/Documenter) guide.

It’s all handwritten markdown right now, and there is no single agreed upon format to document function arguments. That’s why, _in my opinion_, Julia API docs can feel quite messy. Each project does it differently. I frequently run into API docs that haven’t documented function arguments at all, and everything is just `Any` according to the docs (but it never is)

I did some digging a while back and found this relevant discussion: [Argument-specific docstrings or comments](https://discourse.julialang.org/t/argument-specific-docstrings-or-comments/32189), unfortunately that never got any followup.

So for now my suggestion would be to:

1. Pick a style guide you like. SciML, Blue, YAS.
2. Ensure you follow the styleguide by using JuliaFormatter.jl
3. Apply style-specific formatting using custom CSS.

---

<div class="post-metadata">

**Author:** ![CameronBieganek](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cameronbieganek/32/6915_2.png) [@CameronBieganek](https://discourse.julialang.org/u/CameronBieganek)\
**Post date:** [January 3, 2026, 3:33pm UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/10 "2026-01-03T15:33:03Z")

</div>

Copying over some thoughts from a different thread:

I think one of the problems with the Julia documentation is that dozens of functions are documented on the same page, which incentivizes short docstrings. Each generic function should have its own documentation page.

On a somewhat related note, a generic function should only have one meaning, i.e. docstring, for each arity, so other modules that extend a function shouldn’t have any new docstrings unless the new method adds a new arity.

---

<div class="post-metadata">

**Author:** ![kapple](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kapple/32/218915_2.png) [@kapple](https://discourse.julialang.org/u/kapple)\
**Post date:** [January 3, 2026, 11:51pm UTC](https://discourse.julialang.org/t/adopt-the-sciml-style-guide-for-julia-base-and-standard-library/134845/11 "2026-01-03T23:51:09Z")

</div>

I do like attempts to programmatically generate all or some of docstring content like Jieko.jl and DocStringExtensions.jl, and I’ve written my own small adjacent functionalities for my own packages. Too many times I’ve had to access a package’s code to understand exactly what is going on in a method signature because the docstring wasn’t clear enough, or was missing usage information.

Latest example was in the excellent package CoherentNoise.jl for [sample](https://lazarusa.github.io/CoherentNoise.jl/stable/reference/#CoherentNoise.sample) where it states the arguments are of type `Real` but it wasn’t working for my case of mixed `AbstractFloat` and `Integer` instances. I dig into the code to find out that the arguments are all of type `T` with `where {T <: Real}` so all arguments needed to be the same type.

Granted this type of problem is somewhat diagnosable by the `MethodError` that gets thrown, but I wasn’t in the clearest headspace at the time. And this problem could be all the more confusing for a beginner.

I think it’s important we start agreeing on some standardisation of docstring together as a community now. Like others have said, Julia has matured enough for us to start thinking about this.