GitHub リポジトリ命名方針
GitHub のリポジトリ命名方針に関するドキュメントです。
Ateliers プロジェクトで GitHub リポジトリを作成する際に、リポジトリをどのように命名するかについての方針をま とめています。
注意事項
この記事は、個人的な技術利用方針であり、推奨事項やベストプラクティスの主張や提示ではございません。
個人的なアプローチ例の紹介であり、すべてのプロジェクトや環境に最適とは限りませんが、参考にしていただけると幸いです。
1. リポジトリ命名方針の見解
様々な方の GitHub を見てきましたが、正直これには… 明確な正解がないというのが個人的な見解です。
ベストプラクティスの提示なんて、とてもではないですが、できません。
各々のプロジェクトで取り決めをして、チーム内で合意をした命名こそがベストであると考えます。
私は Microsoft の技術をメインとするエンジニアなので、様々な事を Microsoft の方針を元に取り入れますが、Microsoft のリポジトリ命名方針にも、一貫性のある法則を見出す事ができませんでした。
しかし、一般的にはいくつかの法則性が見られましたので、その方針を取り入れてリポジトリを命名する方針にしました。
2. リポジトリ命名方針の概要
リポジトリは、以下の方針を元に命名します。
- 英単語を組み合わせ、単語をハイフン(-) で区切ります。国際的に通用する明瞭な英語を使用します。
- プロジェクトの目的や内容を反映するようにし、短く簡潔にわかりやすい名前を付けます。
- 適切に略語を使用します。使用する場合は、略語の意味を明確にします。
- アルファベットの大文字と小文字を区別しますが、基本的には小文字のみで命名します。大文字のみは避けます。
- ドット(.) を使用は問題ありませんが、基本的には避けます。可能な限りドット(.) をハイフン(-) に置き換えて命名します。
- 数字の使用は可能ですが、先頭には使用しません。
- 特殊文字、スペース、アンダースコアを使用しません。
次に、これらの命名方針の理由を具体化します。
2.1. 命名方針：推奨事項の具体的理由
- 英単語を組み合わせ、単語をハイフン(-) で区切ります。国際的に通用する明瞭な英語を使用します。
基本 中の基本です。意味のある英語で命名し、ハイフン(-) で区切る事で、リポジトリの目的や内容を理解しやすくします。
- プロジェクトの目的や内容を反映するようにし、短く簡潔にわかりやすい名前を付けます。
目的や内容を、ソースコードを見なくても理解できるようにします。また、短く簡潔にわかりやすい名前を付ける事で、他のユーザーがリポジトリを見つけやすくします。
2.2. 命名方針：注意事項の具体的理由
- 適切に略語を使用します。使用する場合は、略語の意味を明確にします。
例えば AI は、略語を使用しないと「Artificial Intelligence」という長い単語になります。
リポジトリの名前としては冗長すぎるため、このケースでは略語を使用する事が適切です。
一方で、略語はリポジトリ名を短く簡潔にする事ができますが、略語の意味が分からないと、リポジトリの内容を理解するのに時間がかかります。
一般的ではない略語は避けるべきで、特にプロジェクト固有の略語を使用する場合は、注意が必要です。
意味が伝わることが、最も重要です。
- アルファベットの大文字と小文字を区別しますが、基本的には小文字のみで命名します。大文字のみは避けます。
これは完全にスタイルの好みの問題です。大文字を使わないことに異を唱える方もおり、正解はありません。
かくいう私も、先頭には大文字を使用する方が好みではありますが、一般的にはあまり見られないため、基本的には小文字のみで命名します。
しかし大文字のみのリポジトリ名は、略語との区別が難しくなるため、避けるようにします。
- ドット(.) を使用しても問題ありませんが、基本的には避けます。可能な限りドット(.) をハイフン(-) に置き換えて命名します。
ドット(.) を使用は可能であり大きな問題とはなりませんが、基本的には避けます。特に C# のプロジェクトを作成する場合、ドット(.) を使用する事が多いですが（初期作成時に推奨されますが）リポジトリ名にドット(.) を使用すると、URL との判別が難しくなります。
他の言語から見るとあまり一般的な命名ではないため、可能な限りドット(.) をハイフン(-) に置き換えて命名します。
2.3. 命名方針：禁止事項の具体的理由
- 数字の使用は可能ですが、先頭には使用しません。
数字の使用自体には、問題ありません。
しかし先頭に数字を使用すると一部のシステムで認識されない可能性があるため、使用しないようにします。
（例えば C# は、数字から始まるネームスペースは使用できません。）
- 特殊文字、スペース、アンダースコアを使用しません。
これは仕様上、システムで正しく認識されなくなる可能性があるので、避けるようにします。
3. 言語別のリポジトリ命名方針
言語ごとにリポジトリ命名方針が異なる場合があるため、ここでは各言語のリポジトリ命名方針を記載します。
3.1. 非言語系のリポジトリ
非言語とは、プログラミング言語以外のリポジトリの事と定義します。
例えば ateliers.dev ウェブサイトのリポジトリは、非言語系のリポジトリとなります。
（厳密には Docusaurus は TypeScript で記述されていますが、目的はウェブサイトの公開であるため、非言語系のリポジトリとして扱います。）
現在のところ、非言語系のリポジトリ命名方針の追加は、特にありません。
3.1.1. 非言語系のリポジトリ命名の例
ドメイン ateliers.dev の場合、リポジトリ名は ateliers-dev とします。
ドット(.) をハイフン(-) に置き換えて命名します。
3.2. C# のリポジトリ
基本方針に加えて、以下の方針を元に命名します。
- 名前空間と同じ名前を使用します。
3.2.1. C# のリポジトリ命名の例
中核となるコアライブラリである Ateliers.Core の場合、リポジトリ名は ateliers-core とします。
大文字を小文字に変換し、ドット(.) をハイフン(-) に置き換えて命名します。
名前空間の命名は GitHub のガイドラインとは内容が異なるため、ここでは省略します。
名前空間についての詳細は、C# 名前空間の命名方針 を参照してください。
4. 命名規則の例外ケース
現在のところ、例外ケースの追加は、特にありません。