2020-05-09

5/9

シェルスクリプトのドキュメントコメントをPODで書くのはもうやめていいかな

いつだったか、何かの本でそういう書き方を見てからずっとそうやってる。

例:

#!/usr/bin/env bash

:

exit 0

: <<'__EOF__'

=encoding utf8

=head1 NAME

B<my-script> - short description

=head1 DESCRIPTION

:

=cut

__EOF__

これでPODに食わせるとドキュメントとして解釈してくれるので、スクリプト内では pod2text $0 とかでヘルプを表示できる。

…が、そろそろ pod2text がどの環境にも入っていると想定すべきでないかも…という気がしてきた。
ところが、じゃあどう書いたらいいの?っていうのには決定版がない気がする。

シェルスクリプトにちゃんとコメントを書こうとしている人たちの間では、主に2つの派閥がある気がする:

  1. スクリプトのヘッダや関数のヘッダとしてドキュメントコメントをそれなりのフォーマットで書きましょう派。Googleのコーディング規約もこれ
  2. usage() 関数内にヒアドキュメントで書きましょう派

いいとこ取りをしてる感じに見えるのは、 usage() 関数でコメントをパースしてヘルプっぽく出力してるもの。
下のような例があった:

自分で独自フォーマットのコメントを書いている、という点では、下もこの類型にあたるか:

godocみたいなのないかな、と思って「shelldoc」とか「shdoc」とかでぐぐるとたくさん出てくる。

参考:

Microk8sを使ってみる

※ブログに移した: UbuntuでKubernetesのテスト環境としてMicrok8sをセットアップした - progrhyme’s tech blog