Style Guide

以下のセクションでは、Juliaらしいコーディングスタイルのいくつかの側面を説明します。これらのルールは絶対的なものではなく、Juliaに慣れ、複数の設計案から選ぶ際の参考となる提案です。

Indentation

インデントの各レベルには、スペースを4つ使います。

Write functions, not just scripts

トップレベルに一連の手順としてコードを書くのは、問題解決に取りかかる手っ取り早い方法です。しかし、できるだけ早くプログラムを関数に分割するようにしましょう。関数にすると再利用やテストがしやすくなり、どのような手順を実行するのか、またその入力と出力が何かも明確になります。さらに、Juliaのコンパイラの仕組みにより、関数内のコードはトップレベルのコードよりも大幅に高速に実行される傾向があります。

また、関数はグローバル変数を直接操作するのではなく、引数を受け取るようにするのが望ましい点も強調しておきます(piのような定数は除きます)。

Write docstrings

オブジェクトを説明するコメントは、エディターやREPLから参照できるよう、通常はdocstringsとして記述します。インラインコメント(# comment)や複数行コメント(#= comment =#)は、ユーザーではなくコードを読む人だけに伝える情報を書く場合に適しています。

Avoid writing overly-specific types

コードはできるだけ汎用的に書きましょう。次のように書くよりも、

Complex{Float64}(x)

利用可能な汎用関数を使うほうが適切です。

complex(float(x))

後者では、xが常に同じ型になるのではなく、適切な型に変換されます。

このスタイル上の注意点は、特に関数の引数に当てはまります。たとえば、実際には任意の整数を受け取れるのであれば、引数をInt型やInt32型に限定せず、抽象型のIntegerで表現しましょう。実際、多くの場合、他のメソッド定義との曖昧さを解消する必要がなければ、引数の型を省略できます。必要な操作をサポートしない型が渡された場合は、いずれにせよMethodErrorがスローされるからです(これはduck typingと呼ばれます)。

たとえば、引数に1を加えた値を返す関数addoneについて、次の定義を考えてみましょう。

addone(x::Int) = x + 1                 # works only for Int
addone(x::Integer) = x + oneunit(x)    # any integer type
addone(x::Number) = x + oneunit(x)     # any numeric type
addone(x) = x + oneunit(x)             # any type supporting + and oneunit

最後の定義のaddoneは、oneunit(xと同じ型で1を返すため、不要な型昇格を避けられます)と、その引数に対する+をサポートする任意の型を扱います。重要なのは、汎用的なaddone(x) = x + oneunit(x)だけを定義しても、性能上の不利益はないということです。Juliaは必要に応じて、特殊化したバージョンを自動的にコンパイルします。たとえば、addone(12)を初めて呼び出すと、Juliaはx::Int型の引数に特化したaddone関数を自動的にコンパイルし、oneunitの呼び出しをインライン化された値1に置き換えます。したがって、上記の最初の3つのaddoneの定義は、4つ目の定義があれば完全に不要です。

Handle excess argument diversity in the caller

次のように書く代わりに、

function foo(x, y)
    x = Int(x); y = Int(y)
    ...
end
foo(x, y)

次のように書きましょう。

function foo(x::Int, y::Int)
    ...
end
foo(Int(x), Int(y))

fooがあらゆる型の数値を受け取れるわけではなく、実際にはIntを必要とするため、こちらのほうが適切なスタイルです。

ここでの問題の一つは、関数が本質的に整数を必要とする場合、整数以外の値をどう変換するか(たとえば、切り捨てるか切り上げるか)を呼び出し側に決めてもらうほうがよい場合があることです。また、より具体的な型を宣言しておけば、将来メソッドを定義するための「余地」を広く残せます。

Append ! to names of functions that modify their arguments

次のように書く代わりに、

function double(a::AbstractArray{<:Number})
    for i in eachindex(a)
        a[i] *= 2
    end
    return a
end

次のように書きましょう。

function double!(a::AbstractArray{<:Number})
    for i in eachindex(a)
        a[i] *= 2
    end
    return a
end

Julia Baseではこの規約が一貫して使われており、コピーする形式と変更する形式の両方を持つ関数(たとえばsortとsort!)や、変更する形式だけを持つ関数(たとえばpush!、pop!、splice!)の例があります。このような関数は、利便性のため、変更後の配列も返すのが一般的です。

IOや乱数生成器(RNG)を扱う関数は、注目すべき例外です。これらの関数はほぼ必ずIOやRNGを変更するため、名前の末尾に!が付く関数は、IOの変更やRNG状態の更新以外の変更を示します。たとえば、rand(x)はRNGを変更しますが、rand!(x)はRNGとxの両方を変更します。同様に、read(io)はioを変更しますが、read!(io, x)は両方の引数を変更します。

Avoid strange type Unions

Union{Function,AbstractString}のような型は、設計をもっとすっきりさせられる可能性を示すことがよくあります。

Avoid elaborate container types

次のような配列を作っても、たいていはあまり役に立ちません。

a = Vector{Union{Int,AbstractString,Tuple,Array}}(undef, n)

この場合はVector{Any}(undef, n)のほうが適切です。また、多くの選択肢を一つの型に詰め込もうとするより、具体的な使用箇所(たとえばa[i]::Int)に注釈を付けるほうが、コンパイラにとっても有益です。

Prefer exported methods over direct field access

Juliaらしいコードでは、通常、モジュールがエクスポートするメソッドを、その型のインターフェースとして扱います。オブジェクトのフィールドは一般に実装の詳細とみなされるため、APIとして明記されている場合を除き、ユーザーコードから直接アクセスすべきではありません。これには次のような利点があります。

  • パッケージ開発者は、ユーザーコードを壊さずに実装を変更しやすくなります。
  • メソッドは、mapのような高階の構文に渡せます(たとえばmap(imag, zs))。[z.im for z in zs]を使う必要はありません。
  • 抽象型に対してメソッドを定義できます。
  • メソッドによって、異なる型に共通する概念上の操作を表現できます(たとえばreal(z)は複素数にも四元数にも使えます)。

Juliaのディスパッチシステムは、このスタイルを後押しします。play(x::MyType)は、その特定の型に対するplayメソッドだけを定義し、他の型にはそれぞれ独自の実装を用意できるからです。

同様に、エクスポートされていない関数は、ドキュメントに別段の記載がない限り、通常は内部向けであり、変更される可能性があります。何かが「内部向け」または実装の詳細であることを示すため、名前に_の接頭辞(または接尾辞)を付けることもありますが、これは規則ではありません。

この規則の例外として、NamedTuple、RegexMatch、StatStructがあります。

Use naming conventions consistent with Julia base/

  • モジュール名と型名には、大文字とキャメルケースを使います。例:module SparseArrays、struct UnitRange。
  • 定数名には、すべて大文字とアンダースコアを使います(LOAD_PATH、VERSION)。
  • publicまたはexportが付いていないものは内部向けとみなされますが、_の接頭辞も、そのオブジェクトが公開用途を想定していないことを示します。
  • 1つ以上の引数を変更する関数の名前は、!で終わります。
  • 簡潔さは重視されますが、略語は避けましょう(indxinではなくindexin)。略語を使うと、特定の単語が略されているか、またどのように略されているかを覚えにくくなるためです。

関数名に複数の単語が必要な場合は、複数の概念を表している可能性がないか、また、名前を分割したほうがよくないかを検討しましょう。

関数名にはスネークケースを使います(minimum、count_zeros、escape_string)。Baseでは単語をつなげてこの規則を破ることがよくあります(splitpath、readeach)が、パッケージではこのスタイルは推奨されません。

Write functions with argument ordering similar to Julia Base

一般に、Baseライブラリでは、該当する場合、関数の引数を次の順序で指定します。

  1. 関数引数。関数引数を先頭に置くと、複数行の無名関数を渡す際にdoブロックを使えます。
  2. I/Oストリーム。IOオブジェクトを先頭に置くと、sprintのような関数に渡せます(例:sprint(show, x))。
  3. 変更対象の入力。たとえばfill!(x, v)では、変更対象のオブジェクトであるxが、xに挿入する値より前に置かれています。
  4. 型。型を渡す場合、通常は出力がその型になります。parse(Int, "1")では、解析する文字列より前に型を指定します。型を先頭に置く例は多数ありますが、read(io, String)ではIO引数が型より前に置かれており、これはここで示す順序に沿っています。
  5. 変更対象ではない入力。fill!(x, v)では、vは変更されず、xの後に置かれています。
  6. キー。連想コレクションでは、キーと値のペアのキーです。それ以外のインデックス付きコレクションでは、インデックスです。
  7. 値。連想コレクションでは、キーと値のペアの値です。fill!(x, v)のような場合は、vがこれに当たります。
  8. その他すべて。上記以外の引数です。
  9. 可変長引数。関数呼び出しの末尾にいくつでも列挙できる引数です。たとえばMatrix{T}(undef, dims)では、次元をTuple(例:Matrix{T}(undef, (1,2)))として指定することも、複数のVararg(例:Matrix{T}(undef, 1, 2))として指定することもできます。
  10. キーワード引数。Juliaでは関数定義のキーワード引数は末尾に置く必要があります。ここでは網羅性のために挙げています。

ほとんどの関数が上記のすべての種類の引数を受け取るわけではありません。番号は、該当する引数がある場合に適用する優先順位を示しています。

もちろん、例外もいくつかあります。たとえばconvertでは、型を必ず先頭に置きます。setindex!では、インデックスを可変長引数として指定できるよう、値をインデックスより前に置きます。

APIを設計する際は、できるだけこの一般的な順序に従うと、関数を使う人にとって一貫性のある使い心地になります。

Don't overuse try-catch

エラーを捕捉することに頼るより、エラーが起きないようにするほうが望ましいです。

Don't parenthesize conditions

Juliaでは、ifやwhileの条件を括弧で囲む必要はありません。次のように書きます。

if a == b

次のように書くのではなく、

if (a == b)

Don't overuse ...

関数引数のスプライスは、つい多用しがちです。[a..., b...]とする代わりに、配列をすでに連結できる[a; b]をそのまま使いましょう。[a...]よりcollect(a)のほうが適切ですが、aはすでに反復可能なので、そのまま使い、配列に変換しないほうがよい場合もよくあります。

Ensure constructors return an instance of their own type

型Tに対してメソッドT(x)を呼び出した場合、通常は型Tの値が返ると期待されます。予期しない型を返すconstructorを定義すると、挙動が分かりにくく、予測しにくくなることがあります。

julia> struct Foo{T}
           x::T
       end

julia> Base.Float64(foo::Foo) = Foo(Float64(foo.x))  # Do not define methods like this

julia> Float64(Foo(3))  # Should return `Float64`
Foo{Float64}(3.0)

julia> Foo{Int}(x) = Foo{Float64}(x)  # Do not define methods like this

julia> Foo{Int}(3)  # Should return `Foo{Int}`
Foo{Float64}(3.0)

コードの明確さを保ち、型の一貫性を確保するため、コンストラクターは、構築対象の型のインスタンスを返すように設計してください。

Don't use unnecessary static parameters

次の関数シグネチャは、

foo(x::T) where {T<:Real} = ...

次のように書くべきです。

foo(x::Real) = ...

特に、関数本体でTを使わない場合はそうしてください。Tを使う場合でも、都合がよければtypeof(x)に置き換えられます。性能差はありません。これは静的パラメーター全般を避けるべきだという注意ではなく、不要な場面で使うことを避けるべきだという注意です。

また、特にコンテナー型では、関数呼び出しで型パラメーターが必要になる場合があります。詳しくはFAQのAvoid fields with abstract containersを参照してください。

Avoid confusion about whether something is an instance or a type

次のような定義の組み合わせは分かりにくくなります。

foo(::Type{MyType}) = ...
foo(::MyType) = foo(MyType)

対象の概念をMyTypeとして表すのか、MyType()として表すのかを決め、一貫させましょう。

基本的にはインスタンスを使い、問題の解決に必要になった場合に限って、後からType{MyType}を使うメソッドを追加するのが望ましいスタイルです。

型が実質的に列挙型である場合は、単一の型(できれば不変の構造体またはプリミティブ型)として定義し、列挙値はそのインスタンスとして表すべきです。コンストラクターや変換処理で、値が有効かどうかを検証できます。この設計は、列挙型を抽象型として定義し、そのサブタイプを「値」とする方法よりも望ましいものです。

Don't overuse macros

マクロではなく関数にできないか、よく検討しましょう。

マクロ内でevalを呼び出している場合は、特に注意が必要です。これは、そのマクロがトップレベルで呼び出された場合にしか動作しないことを意味します。そのようなマクロを関数として書けば、必要な実行時の値を自然に利用できます。

Don't expose unsafe operations at the interface level

ネイティブポインターを使う型がある場合、

mutable struct NativeType
    p::Ptr{UInt8}
    ...
end

次のような定義は書かないでください。

getindex(x::NativeType, i) = unsafe_load(x.p, i)

この型のユーザーが、操作が安全でないと気づかずにx[i]と書き、メモリ関連のバグに遭遇するおそれがあるためです。

このような関数では、操作が安全であることを確認するか、呼び出し側に警告するため、名前のどこかにunsafeを含めるべきです。

Don't overload methods of base container types

次のような定義を書くことは可能です。

show(io::IO, v::Vector{MyType}) = ...

これにより、特定の新しい要素型を持つベクトルを独自の形式で表示できます。魅力的に思えるかもしれませんが、避けるべきです。Vector()のようなよく知られた型には、ユーザーが期待する挙動があります。その挙動を過度にカスタマイズすると、扱いにくくなる可能性があります。

Avoid type piracy

「型の海賊行為(type piracy)」とは、自分が定義していない型に対して、Baseや他のパッケージのメソッドを拡張または再定義することです。極端な場合には、Juliaをクラッシュさせることもあります(たとえば、メソッドの拡張や再定義によって、無効な入力がccallに渡される場合)。型の海賊行為はコードの推論を難しくし、予測や診断が困難な非互換性を引き起こす可能性があります。

例として、あるモジュールでシンボルに対する乗算を定義したいとします。

module A
import Base.*
*(x::Symbol, y::Symbol) = Symbol(x,y)
end

問題は、これによりBase.*を使う他のモジュールからも、この定義が見えるようになることです。SymbolはBaseで定義され、他のモジュールでも使われているため、無関係なコードの挙動が予期せず変わる可能性があります。別の関数名を使う、あるいはSymbolを自分で定義した別の型でラップするなど、いくつかの代替策があります。

機能と定義を分離するため、連携するパッケージ同士が型の海賊行為を行う場合もあります。特に、共同で開発した作者によって設計されたパッケージで、定義を再利用できる場合に見られます。たとえば、あるパッケージが色を扱うための型を提供し、別のパッケージが色空間間の変換を可能にするメソッドをその型に定義することがあります。また、Cコードの薄いラッパーとして機能するパッケージを、別のパッケージが型の海賊行為によって拡張し、より高水準でJuliaらしいAPIを実装する例もあります。

Be careful with type equality

型を判定するには、通常、==ではなく、isaと<:を使います。型の完全一致を調べるのが適切なのは、既知の具象型(たとえばT == Float64)と比較する場合か、自分が何をしているかを本当に十分理解している場合に限られます。

Don't write a trivial anonymous function x->f(x) for a named function f

高階関数は無名関数とともに呼び出されることが多いため、無名関数を使うのが望ましい、あるいは必須だと思いがちです。しかし、どの関数も無名関数で「ラップ」せずに直接渡せます。map(x->f(x), a)と書く代わりに、map(f, a)と書きましょう。

Avoid using floats for numeric literals in generic code when possible

数値を扱い、多様な数値型の引数で実行されることが想定される汎用コードを書く場合は、型昇格による引数への影響ができるだけ小さい数値型のリテラルを使いましょう。

たとえば、

julia> f(x) = 2.0 * x
f (generic function with 1 method)

julia> f(1//2)
1.0

julia> f(1/2)
1.0

julia> f(1)
2.0

一方、

julia> g(x) = 2 * x
g (generic function with 1 method)

julia> g(1//2)
1//1

julia> g(1/2)
1.0

julia> g(1)
2

このように、Intリテラルを使った後者では、入力引数の型が保たれていますが、前者では保たれていません。これは、たとえばpromote_type(Int, Float64) == Float64となり、乗算時に型昇格が起きるためです。同様に、RationalリテラルはFloat64リテラルより型への影響が小さいものの、Intよりは影響が大きくなります。

julia> h(x) = 2//1 * x
h (generic function with 1 method)

julia> h(1//2)
1//1

julia> h(1/2)
1.0

julia> h(1)
2//1

したがって、コードを使いやすくするため、可能な場合はIntリテラルを使い、整数以外の数値リテラルにはRational{Int}を使いましょう。