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 CitationRecipes code follows the rules. When modifying CitationRecipes, 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

CitationRecipes uses JuliaFormatter as an auto-formatting tool.

We use the options contained in .JuliaFormatter.toml.

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

julia> using Pkg
julia> Pkg.add("JuliaFormatter")   Resolving package versions...
    Updating `~/.julia/packages/CitationRecipes/WzE2J/docs/build/developers/Project.toml`
  [98e50ef6] + JuliaFormatter v1.0.24
    Updating `~/.julia/packages/CitationRecipes/WzE2J/docs/build/developers/Manifest.toml`
  [00ebfdb7] + CSTParser v3.3.6
  [a80b9123] + CommonMark v0.8.10
  [34da2185] + Compat v4.6.1
  [a8cc5b0e] + Crayons v4.1.1
  [864edb3b] + DataStructures v0.18.13
  [c27321d9] + Glob v1.3.0
  [682c06a0] + JSON v0.21.3
  [98e50ef6] + JuliaFormatter v1.0.24
  [bac558e1] + OrderedCollections v1.4.1
  [69de0a69] + Parsers v2.5.8
  [21216c6a] + Preferences v1.3.0
  [66db9d55] + SnoopPrecompile v1.0.3
  [0796e94c] + Tokenize v0.5.25
  [5c2747f8] + URIs v1.4.2
  [0dad84c5] + ArgTools v1.1.1
  [56f22d72] + Artifacts
  [2a0f44e3] + Base64
  [ade2ca70] + Dates
  [f43a241f] + Downloads v1.6.0
  [7b1f6079] + FileWatching
  [b77e0a4c] + InteractiveUtils
  [b27032c2] + LibCURL v0.6.3
  [76f85450] + LibGit2
  [8f399da3] + Libdl
  [37e2e46d] + LinearAlgebra
  [56ddb016] + Logging
  [d6f4376e] + Markdown
  [a63ad114] + Mmap
  [ca575930] + NetworkOptions v1.2.0
  [44cfe95a] + Pkg v1.8.0
  [de0858da] + Printf
  [3fa0cd96] + REPL
  [9a3f8284] + Random
  [ea8e919c] + SHA v0.7.0
  [9e88b42a] + Serialization
  [6462fe0b] + Sockets
  [fa267f1f] + TOML v1.0.0
  [a4e569a6] + Tar v1.10.0
  [cf7118a7] + UUIDs
  [4ec0a83e] + Unicode
  [e66e0078] + CompilerSupportLibraries_jll v0.5.2+0
  [deac9b47] + LibCURL_jll v7.84.0+0
  [29816b5a] + LibSSH2_jll v1.10.2+0
  [c8ffd9c3] + MbedTLS_jll v2.28.0+0
  [14a3606d] + MozillaCACerts_jll v2022.2.1
  [4536629a] + OpenBLAS_jll v0.3.20+0
  [83775a58] + Zlib_jll v1.2.12+3
  [8e850b90] + libblastrampoline_jll v5.1.1+0
  [8e850ede] + nghttp2_jll v1.48.0+0
  [3f19e933] + p7zip_jll v17.4.0+0
julia> using JuliaFormatter: format
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 CitationRecipes 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.