ドキュメントを書く技術 - blog
READMEを始め、ソフトウェアのドキュメント全般を書く技術というものをもっと洗練させていきたい。要件定義書のようなものだけでなく、開発方針や設計方針、API定義などなど。 これらのドキュメントをしっかりと整備するだけで、レビューの質も上がり新しい人が入ったときもスムーズに意識のズレなく開発ができる。はずだが、なかなかドキュメントの上手い書き方や管理の仕方というものは、コーディングのそれとは違い議論が活発ではない。 最近試してみたこと そういったドキュメントの中でも、"開発方針"や"設計思想"をどう残していくかということを考えている。それらを残しておくことで、コーディングのときも立ち戻る場所ができ、大きく道を踏み外さなくなる。 例えば、レイヤードアーキテクチャのようなものの"境界"をドキュメントにしていく。MVCでもクリーンアーキテクチャでも何でも良いけど、それらのアーキテクチャではそれぞ
プログラミングスタイルガイドのスタイルガイド - Qiita
本文書は、プログラミング言語向けのスタイルガイドに向けたスタイルガイドである。 本文書へのフィードバックはQiita上のコメントにて受け付ける。 構造 対象を明確にする そのスタイルガイドがどのような状況のどのような対象に向けたスタイルガイドであるか規定すること。 状況や対象は広すぎてはならない。 理由: 対象はスタイルガイド記述者には自明かもしれないが、似て非なる言語に誤用されたり、特定分野のアプリケーション向けスタイルガイドが他分野のアプリケーションを理不尽に拘束したりすることがある。これを防ぐべきである。 良い例: 「本文書はRuby on Railsアプリケーション向けのスタイルガイドである」 「本スタイルガイドはX社におけるRubyプロジェクトに適用すべきスタイルを規定する」 悪い例: (何も書かない) 「本文書はX社におけるすべての開発に適用される ... 述語メソッドや述語関
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
ドキュメント太平洋戦争 第３集 エレクトロニクスが戦（いくさ）を制す ～マリアナ・サイパン～｜戦争｜NHKアーカイブス
