[ en | ja ]

[ home | blog | progression ]

:: ホーム / ブログ / write the readme ::

2026-03-08 | updated: 2026-03-08

write the readme

本文書は本題"write the readme"の通りREADMEの作成、更新を推奨するものである。

2024年私は大学のプログラミング部において幹事長として部活動を率いた。その部、RyukokuHorizon(^1)、以下RHでは2024年から1年を通して体系的にプログラミングを学ぶ環境が整えられた。RHでは2024,25年の2年間を通して約200ものリポジトリが作られた。そしてそれら大部分が学習目的での開発とはいえ、まともに起動するし、ある程度使い物にもなる。しかし、それらのリポジトリの多くにはREADMEが無い。 なぜREADMEが無いのかといえば文化であり妥当なのだ。RHにおいては、入部後1年は学習が組織により主導、管理される。これにより、Pythonの基本からGit, チーム開発まで学習、経験できるのだが、言い換えれば一つのプロジェクトに腰を据えることができないわけだ。また、チーム開発で必要なコミュニケーションはDiscordとNotion,Cnavaで行われる。それにより決めごとやイントロなど開発自体に必要な要素をリポジトリで管理する必要があまりない。また、学習プロジェクトというのもあり公開することも少ない。これは私もリポジトリをやたらめったに公開する質ではないので理解できる。しかし誰に公開するでもなくREADMEは書くのだが。

ここまでの流れで本文書が主に私の後輩諸君に向けたものだと分かるだろう。しかしおそらくこんな題の文書を読む諸君もその対象であろうと予想できる。

さて、READMEとはテキストファイルである。んな事が聞きたいわけじゃないって？んじゃWikipediaに書いてあった歴史を軽く(^2)。日本語のWikiには書いてないのでまぁ少しくらいは参考になるかもしれない。 READMEの登場は1970年頃だ。当時のコンピュータ、厳密にはUNIXみたいなやつとインターフェイスでは小文字ばっかりファイルが並んでた。もちろん当時のUNIXさんたちは日本語なんて気にも止めなかった。ASCIIだったわけだし。そんなREAMDEはソフトウェアを使うときにはじめに読むやつだ。だから目立ちたがり屋ってわけだ。ファイル名からもReadMe、読んでくれってのが伝わるだろ？今となってはハッカーしか興味を持ちそうにないGNUなんかもパッケージにその概要を含めることを推奨していた。(^3) んなわけで古くからREADMEないし同様の目的をもったファイルをプロジェクトに含めることが勧められてたってわけだ。んでも上に上げたGNUの例はフリーソフトウェア、今で言うオープンソースソフトウェアだから公開目的だから書いてるんだから学習プロジェクトなんかの非公開プロジェクトはいいだろって？

だからこの文書を書いたし、序論で非公開のプロジェクトの話をしてるんだよ。んじゃ非公開プロジェクトで、公開プロエクとはもちろんREADMEを書くべきかって話だけども。 主に4つの理由だ。

  1. 概要説明
  2. 共有事項
  3. 久々のリファクタリング
  4. 記念に

1つめの概要説明は言わずもがな。そのプロジェクトがどうして作られて、何をできて、どういう仕組みか。また、公開する場合はライセンスみたいなものも。RHの後輩諸君を対象に書くべき理由を説明すれば運営側が頭に入れやすいだろうからだ。んでもってファイルを整理したくなったときに、そもそも関わったり作ったプロジェクトが多くなれば、後々なんやねんこれって感じでコードを読まなきゃいけなくなる。そんな作業が楽しくもあるのだが。そんなのはたまたま見つけるくらいじゃないと面倒くさい事この上ない。

2つめは共有事項だ。チャットの履歴はクソだ。そんなチャットの履歴や別媒体はごっちゃになるに違いない。もちろんどっか別の場所に於いて、URLで飛べるようにしていればまた別だけども。わざわざ起動方法をチャットを遡って確認するくらいなら書いとけって話だ。最近のパッケージマネージャなんかはinitやら作成時に書いてくれたりもするらしいが。

3つめはリファクタリングのときだ。これは主にRHの後輩諸君を対象にしたものだ。大学生という身分上諸君の大半は後々就職活動なんてものに挑むことになる。そんでプログラミング部に所属してるんだからIT系を受けることも多いだろう。そんなときに諸君はGitHubのURLやポートフォリオなるもの要求されるかもしれない。そんなときに起動もしないようなプロジェクトばっかりが陳列されてるのは出せないだろう。だからどうせ諸君は起動するものかリファクタリングして起動するようになったものを並べるんだ。んで多くの場合過去に書いたコードはクソだ。どこの猿が書いたんだろうと数年越しに思うかもしれない。んな感じのやつを読むにはREADMEで概要を把握してからのほうがまだましだ。って訳。

4つめはただの記念だ。過去にどんな経緯で、何を作って、何に興味があって、誰と作ったのかが分かると案外たのしいものなのだ。 以上

サラダバー

注釈&参考

  1. RyukokuHorizon: 私が大学時代に所属していたプログラミング部。正式名称は"龍谷大学学友会学術文化局 プログラミン部 Horizon。OBOG組織であるHorizonVerticalとの混同を避けるためRyukokuHorizonとしている。本文書では読みやすさのためRHと省略している。
  2. README | Wikipedia, https://en.wikipedia.org/wiki/README#History.
  3. GNU coding standards | Wikipedia, https://en.wikipedia.org/wiki/GNU_coding_standards.

<< 一覧に戻る