プログラマーじゃない人に覚えてほしいプログラムのコメントの書き方
Top / プログラマーじゃない人に覚えてほしいプログラムのコメントの書き方この記事は、ただの思考実験です。
プログラマじゃない人に、EclipseなどのIDEによるサポートというか恩恵を得るにはどうしたらいいのか考えてみる。
そもそも、どういう恩恵があるのか、静的言語のプログラマじゃないと知らない。
自然言語の設計書とプログラムが一元管理されていてほしいと思うことがある。
その手始めに、非プログラマにコメントの書き方を教えるというのはどうだろうか？
例えば、
文章の先頭に // を付けましょう。以上。 こんな感じになります。 これはリンゴです。 ↓ // これはリンゴです。
↑これだったらプログラマーじゃない人も１０秒もあれば、コメント文の書き方は理解できるはずだ。
markdown形式は次に理解したらいいかもしれない。 理解しなくてもテキストが表現されるし、 理解していたら見栄えが良くなるし。 プログラムに依存してない。
もう少しプログラミングの知識のレベルが進んでもよいのならば、用語の説明には、
// 用語の説明
class 用語名 {
}
ちょっと厳しいのか？
用語のグループ分けはpacageを使うよとか。
そこぐらいまでは、３分ぐらいで理解できるはず。
言葉のブレをなくしつつ、実装しやすい形式で残すことは、正規化されたデータに近づける行為のように思う。
IDEを使えば、数万とかの単語数も管理できる なにがしたいかというと、
markdown形式の中に 実際に動作するコードを入れておくアイデアを考える †
markdownのコメントの書き方に
``` 言語の指定
```
というのがある。
非プログラマにプログラムのコメント風に書いてね。だと通知するコストが高すぎる。
何もプログラムを知らない人が書いたものは、プログラム化する際に自動的にコメントアウトできればいいではないか？
コメントアウトの対象外は上記のmarkdownのコメントアウト指定されたもの以外は自動的にコメントアウト対象外とすればよい。
コメントとソースコードがネガとポジのような関係を持つリポジトリを考えてみる †
コメントリポジトリと、コードリポジトリを用意する。
ルールとしては、片方のリポジトリに変更があると、反転したコードを片方に自動でコミットするものとする
反転ルール †
コメントリポジトリの反転ルール †
コミット時に
markdown形式は、Javaなど指定したコメント形式に反転する。
markdown形式で、Java としてコメント化されている場合は、その箇所をコメントアウトする。
ソースリポジトリの反転ルール †
コミット時に
コメント部分は、markdown形式とする
Javaのコードはmarkdownのコメント形式とする
