基本的には「本リポジトリのコンセプト」を守るようにしてください。コミットする前に、余裕があれば読み返して推敲してください。
その他は時間があれば読んでください。
慎重になりすぎる必要はありません。気づいた人が後から直しましょう。
コードを書きながら学べるコンテンツを目指します。文章と同等量のコードを載せるようにします。また、積極的にコメント文を使ってください。質の悪いコードは載せないようにします。
各項目について詳細すぎる説明はしません。深く学ぶための優れた書籍は他にたくさんあります。 また、海外製の技術書等でよく見られるようなジョークやコラム、豆知識など、本筋から逸れた記述は極力無くします。
表現を統一し、より良い表現を常に追求します。
独自に作った略語を使わないようにします。一般的に使われている略語を使う分には問題ありませんが、事前に定義してください。
項目の内部で遷移することがないようにします。「※」を使った脚注や、「詳細は〜で説明」といった表現を使わないようにします。補足情報があれば、常にその場で簡潔に説明します。簡潔に説明できない場合は詳細すぎる説明になっている可能性を疑ってください。
項目間の依存関係を極力排除します。ある項目を学ぶために他の項目を学ぶ必要がないようにします。どうしても依存関係が生じてしまう場合には、項目の初めに依存先を明示します。
基本的には他の文章と比べて違和感がないようにしていただければ良いです。細かい部分は個人のセンスに任せます。
テンプレートを用意しています。
VS Codeの拡張機能であるテキスト公正くんを使うことを推奨します。設定は、VS Codeの拡張機能「テキスト校正くん」の設定方法を参照してください。
文末は基本的に「〜です」「〜ます」としてください。他にも、「〜ました」や「〜ください」、「～ありません」といった表現が利用できます。
日本語の文脈では、「。」「、」を基本としてください。論文等で扱われる「.」「,」を日本語の文脈で使うことは避けてください。堅い印象を読者に与える可能性があります。
日本語の文脈では全角を、英語の文脈では半角を使ってください。半角カナと全角英数、全角スペースは利用しないでください。
日本語の文脈で利用する括弧は、全角カギ括弧「」または全角丸括弧（）のみとしてください。
英語の文脈で利用する括弧は、半角丸括弧 () のみとしてください。
効果的に空白行や半角スペースを使ってください。理解を促進するためのさまざまな効果が得られます。
文脈のまとまり毎に改行や空白行を設けてください。
文章中に英数字や括弧が出現する場合は、見やすさを考慮して適宜半角スペースを入れてください。
インラインコードの両端に半角スペースを入れてください。
文章に対する相対的な位置の指し示す場合は、極力「次の〜」といったように事前に説明してください。「上記の〜」といった表現を使うことは避けてください。
シェルの場合は、コマンドの入力と出力が明確にわかるように、コマンド入力の先頭に「>」を挿入します。出力が長い場合には「...」を用いて省略できます。
> echo "Hello World!"
Hello World!
> cat sample.txt # sample.txtの内容を表示する
hogehoge
...
ファイルの場合は、 どのファイルの内容であるかを先頭にコメント文を用いて記述します。通常のコメント文と区別するために、両端に「--」を挿入します。ファイルの内容が多い場合には「...」を用いて省略できます。
# -- /path/to/sample.py --
if __name__ == "__main__":
# Hello World!を表示する
print("Hello World!")
...基本的には過去のコミットと比べて違和感がないようにしていただければ良いです。
フォーマットは基本的に次のようにします。
[prefix]: [本文]
prefixはこだわりがない場合は次の表を参照してください。Emoji prefixなどで遊んでいただいても構いません。
| prefix | 説明 |
|---|---|
| Add: | 新規ファイルを作成した / 作成と同時に編集した |
| Update: | ファイルの内容を編集した / 機能を追加・削除した |
| Fix: | 誤字脱字や体裁などに関する軽微な修正をした |
| Move: | ファイルを移動した / ファイル名を変更した |
| Remove: | ファイル自体を削除した |
本文は日本語で書いてください。長くても20文字程度で良いです。5W1Hなど、厳密すぎる必要はありません。日本語の体裁はとくに指定しません。遊んでいただいても構いません。
機能のまとまりごとにコミットしてください。異なる種類のコミットが混在しないようにしてください。初めにコミットメッセージ考え、それを起点に対象のファイルをステージングすることで上手くいくはずです。頻繁すぎるコミットは避けるようにしてください。