Style Guide

This section describes the coding style rules that apply to our code and that we recommend you to use it also.

In some cases, our style guide diverges from Julia's official Style Guide (Please read it!). All such cases will be explicitly noted and justified.

Our style guide adopts many recommendations from the BlueStyle. Please read the BlueStyle before contributing to this package. If not following, your pull requests may not be accepted.

Info

The style guide is always a work in progress, and not all SimpleWorkflowRecipes code follows the rules. When modifying SimpleWorkflowRecipes, please fix the style violations of the surrounding code (i.e., leave the code tidier than when you started). If large changes are needed, consider separating them into another pull request.

Formatting

Run JuliaFormatter

SimpleWorkflowRecipes uses JuliaFormatter as an auto-formatting tool.

We use the options contained in .JuliaFormatter.toml.

To format your code, cd to the SimpleWorkflowRecipes directory, then run:

julia> using Pkg
julia> Pkg.add("JuliaFormatter")   Resolving package versions...
   Installed Glob ─────────── v1.4.0
   Installed JuliaFormatter ─ v2.3.0
   Installed CommonMark ───── v0.10.3
   Installed JuliaSyntax ──── v0.4.10
    Updating `~/work/SimpleWorkflowRecipes.jl/SimpleWorkflowRecipes.jl/docs/build/developers/Project.toml`
  [98e50ef6] + JuliaFormatter v2.3.0
    Updating `~/work/SimpleWorkflowRecipes.jl/SimpleWorkflowRecipes.jl/docs/build/developers/Manifest.toml`
⌅ [a80b9123] + CommonMark v0.10.3
  [c27321d9] + Glob v1.4.0
  [98e50ef6] + JuliaFormatter v2.3.0
⌅ [70703baa] + JuliaSyntax v0.4.10
  [aea7be01] + PrecompileTools v1.3.3
  [21216c6a] + Preferences v1.5.2
  [ade2ca70] + Dates v1.11.0
  [de0858da] + Printf v1.11.0
  [fa267f1f] + TOML v1.0.3
  [4ec0a83e] + Unicode v1.11.0
        Info Packages marked with ⌅ have new versions available but compatibility constraints restrict them from upgrading. To see why use `status --outdated -m`
Precompiling packages...
    570.2 ms  ✓ Glob
  11322.9 ms  ✓ CommonMark
  14646.3 ms  ✓ JuliaSyntax
  25365.7 ms  ✓ JuliaFormatter
  4 dependencies successfully precompiled in 40 seconds. 6 already precompiled.
julia> using JuliaFormatter: formatPrecompiling packages...
Info Given CommonMarkMarkdownASTExt was explicitly requested, output will be shown live 
ERROR: LoadError: ArgumentError: Package MarkdownAST [d0879d2d-cac2-40c8-9cee-1863dc0c7391] is required but does not seem to be installed:
 - Run `Pkg.instantiate()` to install all recorded dependencies.

Stacktrace:
  [1] __require_prelocked(pkg::Base.PkgId, env::String)
    @ Base ./loading.jl:2617
  [2] _require_prelocked(uuidkey::Base.PkgId, env::String)
    @ Base ./loading.jl:2495
  [3] macro expansion
    @ ./loading.jl:2423 [inlined]
  [4] macro expansion
    @ ./lock.jl:376 [inlined]
  [5] __require(into::Module, mod::Symbol)
    @ Base ./loading.jl:2388
  [6] require(into::Module, mod::Symbol)
    @ Base ./loading.jl:2364
  [7] top-level scope
    @ ~/.julia/packages/CommonMark/JRyms/ext/CommonMarkMarkdownASTExt.jl:7
  [8] include(mod::Module, _path::String)
    @ Base ./Base.jl:306
  [9] include_package_for_output(pkg::Base.PkgId, input::String, depot_path::Vector{String}, dl_load_path::Vector{String}, load_path::Vector{String}, concrete_deps::Vector{Pair{Base.PkgId, UInt128}}, source::Nothing)
    @ Base ./loading.jl:3028
 [10] top-level scope
    @ stdin:5
 [11] eval(m::Module, e::Any)
    @ Core ./boot.jl:489
 [12] include_string(mapexpr::typeof(identity), mod::Module, code::String, filename::String)
    @ Base ./loading.jl:2874
 [13] include_string
    @ ./loading.jl:2884 [inlined]
 [14] exec_options(opts::Base.JLOptions)
    @ Base ./client.jl:315
 [15] _start()
    @ Base ./client.jl:550
in expression starting at /home/runner/.julia/packages/CommonMark/JRyms/ext/CommonMarkMarkdownASTExt.jl:3
in expression starting at stdin:5
              ✗ CommonMarkMarkdownASTExt (serial)
  0 dependencies successfully precompiled in 1 seconds

┌ Error: Error during loading of extension CommonMarkMarkdownASTExt of CommonMark, use `Base.retry_load_extensions()` to retry.
│   exception =
│    1-element ExceptionStack:
│    The following 1 direct dependency failed to precompile:
│    
│    CommonMarkMarkdownASTExt 
│    
│    Failed to precompile CommonMarkMarkdownASTExt [982e44cd-a21d-5e22-8cc2-6028175a7989] to "/home/runner/.julia/compiled/v1.12/CommonMarkMarkdownASTExt/jl_uygbrb".
│    ERROR: LoadError: ArgumentError: Package MarkdownAST [d0879d2d-cac2-40c8-9cee-1863dc0c7391] is required but does not seem to be installed:
│     - Run `Pkg.instantiate()` to install all recorded dependencies.
│    
│    Stacktrace:
│      [1] __require_prelocked(pkg::Base.PkgId, env::String)
│        @ Base ./loading.jl:2617
│      [2] _require_prelocked(uuidkey::Base.PkgId, env::String)
│        @ Base ./loading.jl:2495
│      [3] macro expansion
│        @ ./loading.jl:2423 [inlined]
│      [4] macro expansion
│        @ ./lock.jl:376 [inlined]
│      [5] __require(into::Module, mod::Symbol)
│        @ Base ./loading.jl:2388
│      [6] require(into::Module, mod::Symbol)
│        @ Base ./loading.jl:2364
│      [7] top-level scope
│        @ ~/.julia/packages/CommonMark/JRyms/ext/CommonMarkMarkdownASTExt.jl:7
│      [8] include(mod::Module, _path::String)
│        @ Base ./Base.jl:306
│      [9] include_package_for_output(pkg::Base.PkgId, input::String, depot_path::Vector{String}, dl_load_path::Vector{String}, load_path::Vector{String}, concrete_deps::Vector{Pair{Base.PkgId, UInt128}}, source::Nothing)
│        @ Base ./loading.jl:3028
│     [10] top-level scope
│        @ stdin:5
│     [11] eval(m::Module, e::Any)
│        @ Core ./boot.jl:489
│     [12] include_string(mapexpr::typeof(identity), mod::Module, code::String, filename::String)
│        @ Base ./loading.jl:2874
│     [13] include_string
│        @ ./loading.jl:2884 [inlined]
│     [14] exec_options(opts::Base.JLOptions)
│        @ Base ./client.jl:315
│     [15] _start()
│        @ Base ./client.jl:550
│    in expression starting at /home/runner/.julia/packages/CommonMark/JRyms/ext/CommonMarkMarkdownASTExt.jl:3
│    in expression starting at stdin:
└ @ Base loading.jl:1619
Precompiling packages...
    545.3 ms  ✓ CommonMarkMarkdownExt (serial)
  1 dependency successfully precompiled in 1 seconds
julia> format("docs");ERROR: IOError: realpath("docs"): no such file or directory (ENOENT)
julia> format("src");ERROR: IOError: realpath("src"): no such file or directory (ENOENT)
julia> format("test");ERROR: IOError: realpath("test"): no such file or directory (ENOENT)

Info

A continuous integration check verifies that all PRs made to SimpleWorkflowRecipes have passed the formatter.

The following sections outline extra style guide points that are not fixed automatically by JuliaFormatter.

Use the Julia extension for Visual Studio Code

Please use VS Code with the Julia extension to edit, format, and test your code. We do not recommend using other editors to edit your code for the time being.

This extension already has JuliaFormatter integrated. So to format your code, follow the steps listed here.