ドキュメンテーション

team moc

2021-10-09

• prop ソースコードは参考にしたURLとかdoccommentとかたくさん書いてself-containedにすべきか？
  • プロダクションソースにはあまり書きたくないという意見
  • サーバーサイド&非公開でも？
  • レビュアーの目線から考えると？
  • tips的なコメントが増えてノイズになるというのはある

2022-03-02
やはり, コードとドキュメントの距離をなるべく小さくするのが是だと思う

• Rust のdoc commentとかはサンプルコードもコンパイルされテストが走るらしいし理想に近い

• validation: 妥当性 仕様が利用者の価値に見合うか

• verification: 正当性 システムが利用者の価値に見合うか

• verification $\subset$ validation

• idea TSのDoc commentを抜き出してテストするツール作るか

  • GitHub - jonschlinkert/esprima-extract-comments: Extract javascript code comments with esprima. Thin wrapper to prove a simple interface for getting code comments from a string, file or glob of files.

2022-03-04

• 試験項目表もマトリクステーブルもつらそう

• 仕様(= 制約)をなにかしらのDSLで書けて, それをもとにコーナーケースのテストを自動で出来たらうれしそう

• Formal Specification Language というらしい

• idea docsのtypoの為だけにissueたてるの面倒くさい人もいそうだからdocs上でワンクリックでissue化出来る拡張機能か何かがあると良さそう

2022-04-17

• HTTPキャッシュに学ぶ、無理のないドキュメント更新運用
  -「なるべくみんなに負荷をかけず、かつ死なずに運用されるドキュメント更新の仕組みづくり」
  • 自分が抱いているドキュメンテーションへの課題
  • ソースコードとドキュメントの関係をHTTPキャッシュに喩えている
  • ライブドキュメント という考え方

参考文献