Skip to content

Commit 8b14690

Browse files
authored
Clarify style guidance for contributors and package authors (#57577)
- Deduplicate style guide in CONTRIBUTING.md and manual/style-guide.md - Link from CONTRIBUTING.md to the manual - Clarify contradictory function naming guidance I took out the "Underscores are also used to indicate a combination of concepts" language because I don't think that accurately reflects when base uses snake case.
1 parent 123a556 commit 8b14690

File tree

2 files changed

+7
-7
lines changed

2 files changed

+7
-7
lines changed

CONTRIBUTING.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -345,13 +345,11 @@ please remove the `backport-X.Y` tag from the originating pull request for the c
345345

346346
#### General Formatting Guidelines for Julia code contributions
347347

348-
- 4 spaces per indentation level, no tabs
348+
- Follow the latest dev version of [Julia Style Guide](https://docs.julialang.org/en/v1/manual/style-guide/).
349349
- use whitespace to make the code more readable
350350
- no whitespace at the end of a line (trailing whitespace)
351351
- comments are good, especially when they explain the algorithm
352352
- try to adhere to a 92 character line length limit
353-
- use upper camel case convention for modules, type names
354-
- use lower case with underscores for method names
355353
- it is generally preferred to use ASCII operators and identifiers over
356354
Unicode equivalents whenever possible
357355
- in docstrings refer to the language as "Julia" and the executable as "`julia`"

doc/src/manual/style-guide.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -172,17 +172,19 @@ Counter-examples to this rule include [`NamedTuple`](@ref), [`RegexMatch`](@ref
172172
## Use naming conventions consistent with Julia `base/`
173173

174174
* modules and type names use capitalization and camel case: `module SparseArrays`, `struct UnitRange`.
175-
* functions are lowercase ([`maximum`](@ref), [`convert`](@ref)) and, when readable, with multiple
176-
words squashed together ([`isequal`](@ref), [`haskey`](@ref)). When necessary, use underscores
177-
as word separators. Underscores are also used to indicate a combination of concepts ([`remotecall_fetch`](@ref)
178-
as a more efficient implementation of `fetch(remotecall(...))`) or as modifiers.
175+
* constants use all uppercase and underscores ([`LOAD_PATH`](@ref), [`VERSION`](@ref)).
176+
* while anything not marked with `public` or `export` is considered internal, a prefix of
177+
`_` also indicates that an object is not intended for public use.
179178
* functions mutating at least one of their arguments end in `!`.
180179
* conciseness is valued, but avoid abbreviation ([`indexin`](@ref) rather than `indxin`) as
181180
it becomes difficult to remember whether and how particular words are abbreviated.
182181

183182
If a function name requires multiple words, consider whether it might represent more than one
184183
concept and might be better split into pieces.
185184

185+
Function names should be written in snake case ([`minimum`](@ref), [`count_zeros`](@ref), [`escape_string`](@ref)).
186+
Base often breaks this convention by squashing words together ([`splitpath`](@ref), [`readeach`](@ref)) but this style is not recommended for packages.
187+
186188
## Write functions with argument ordering similar to Julia Base
187189

188190
As a general rule, the Base library uses the following order of arguments to functions,

0 commit comments

Comments
 (0)