Documentation: Import JuliaPraxis guidelines. #25204
Description
JuliaPraxis is an organization that emerged from the need to talk about "Julia: Best Practices", there has been lots of discussions and some advances but recently it has been brought to my attention, that the current JuliaPraxis effort could be potentially ignored, because those guidelines are not part of this repository.
So I think we need to start importing those guidelines over here while discussing them in order to reach consensus on which could be considered "official" guidelines, so we can enforce them later with the aim to make the language more consistent, so others can follow the example laid out in this repository for the Julia code style and conventions.
To do:
- Bike shed cryptic top level identifier names (starting by priority with exported ones, but also including non exported ones.)
- Bike shed keyword argument names (:warning: breaking, would need to be done before 1.0, but we already have code freeze.)
- Bike shed better positional argument names post 1.0
Related (mostly all the "rename x" open issues), but style also includes any kind of "refactoring tips" found in other issues, or just "best practices" in general (including for example things like documenting and coverage practices too.) Here a list of the most recent ones:
- Replace "key" terminology with "index" terminology #25104
- rename Void => Nothing with alias Cvoid = Nothing #25082
- Deprecate findin(a, b) in favor or find(occursin(b), a) #24967
- Renaming findn and findnz? #24910
- https://github.com/JuliaLang/julia/issues/25118
- Rename findmin and findmax? #24865
- Renaming findn and findnz? #24910
- Rename pwd() to cwd() #24815
- Rename issparse? #24645
- Rename realmin -> realabsmin? #23710
- Rename Hessenberg to HessenbergFactorization LinearAlgebra.jl#462
- Rename Base.runtests() to Base.test() #23482
- [doc] rename outer-only constructors? #23022
- Rename
haskeytohasindex#25105 - Rename unshift!/shift! to pushfirst!/popfirst! #25100
- Renaming Catalan's constant so Catalan numbers can be defined more na… #12706
- RFC: add cleandeps keyword argument to Pkg.rm #12350
In the cases where JuliaPraxis suggestions are deemed inappropriate, such suggestions should be replaced with appropriate ones we can agree from the stylistic and naming patterns currently in use here.
So that all the issues/PRs that reflect agreement about any type of stylistic convention, should be properly documented along with the other guidelines, for the sake of consistency.
Priority would be naming style and conventions, since those are user-facing (part of APIs), and would extend to syntactic, workflow, tips, etc. type of guidelines.