[memo] Add 20200509

content/ja/a/memo/20200430.md → content/ja/a/memo/2020/20200430.md

@@ -62,3 +62,9 @@ tfenv: tfenv-install: [ERROR] Tarball unzip failed
 - `/usr/bin/unzip some.zip -d somedir` は成功する。
 
 単独でunzipコマンドを実行しても失敗しているので、Linuxbrewのunzipが壊れてるんだと思う。
+
+#### 5/9 追記
+
+これ、GCEにDebian 10とUbuntu 18.04とCent OS 8のVMを立てて追試したところ、全部linuxbrewのunzipが正常に動いた。
+
+なぜだ。。

content/ja/a/memo/20200509.md

@@ -0,0 +1,63 @@
+---
+title: "2020-05-09"
+linkTitle: "2020-05-09"
+date: 2020-05-09T15:48:56+09:00
+---
+
+## 5/9
+### シェルスクリプトのドキュメントコメントをPODで書くのはもうやめていいかな
+
+いつだったか、何かの本でそういう書き方を見てからずっとそうやってる。
+
+例:
+
+```sh
+#!/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のコーディング規約](https://google.github.io/styleguide/shellguide.html#s4.1-file-header)もこれ
+1. `usage()` 関数内にヒアドキュメントで書きましょう派
+
+いいとこ取りをしてる感じに見えるのは、 `usage()` 関数でコメントをパースしてヘルプっぽく出力してるもの。  
+下のような例があった:
+
+- [シェルスクリプトでヘルプメッセージをコメントに書いて表示する - Qiita](https://qiita.com/ngyuki/items/673d6cb3b36360eaf5cc)
+- [自作シェルスクリプトにヘルプやらバージョンメッセージを実装？する面白い方法があった - Qiita](https://qiita.com/TomKid/items/ab49f8d0cd15b18e5e4a)
+
+自分で独自フォーマットのコメントを書いている、という点では、下もこの類型にあたるか:
+
+- [シェルスクリプト群のドキュメント書くの面倒だから自動でREADME.mdを生成する - Qiita](https://qiita.com/ssh0/items/0c14ee8949512a4dc98e)
+- https://github.com/jmcantrell/bashful/blob/master/bin/shdoc
+
+godocみたいなのないかな、と思って「shelldoc」とか「shdoc」とかでぐぐるとたくさん出てくる。
+
+参考:
+
+- [シェルスクリプト Tips | UNIX &amp; Linux コマンド・シェルスクリプト リファレンス](https://shellscript.sunone.me/tips.html)