ドキュメントを書く技術 - blog
READMEを始め、ソフトウェアのドキュメント全般を書く技術というものをもっと洗練させていきたい。要件定義書のようなものだけでなく、開発方針や設計方針、API定義などなど。 これらのドキュメントをしっかりと整備するだけで、レビューの質も上がり新しい人が入ったときもスムーズに意識のズレなく開発ができる。はずだが、なかなかドキュメントの上手い書き方や管理の仕方というものは、コーディングのそれとは違い議論が活発ではない。 最近試してみたこと そういったドキュメントの中でも、"開発方針"や"設計思想"をどう残していくかということを考えている。それらを残しておくことで、コーディングのときも立ち戻る場所ができ、大きく道を踏み外さなくなる。 例えば、レイヤードアーキテクチャのようなものの"境界"をドキュメントにしていく。MVCでもクリーンアーキテクチャでも何でも良いけど、それらのアーキテクチャではそれぞ
エンジニアの10大ウソ · dongri
後でコメント付けるから これは暫定的な方法、本番リリース時はこの方法で書かない 大体終わった。後小さい問題何個か残ってるだけ エンジニア：”十日は必要”。Boss：”五日でできる？”。エンジニア：”できる！” TODO 私の端末ではちゃんと動くのに これはテストする必要ない、絶対問題ないから そう、もうテストした 一行の修正だけ、他の処理に影響しない これは前からあった問題 追加10ウソ 次コード修正する時ユニットテスト書くよ ９０％は終わった これは二分で解決できる そう、これは既知のBugだ 昨日はちゃんと動いてたのに そんなのありえない これはハードウェア/ネットワークの問題、私のコードと関係ない これはBugではなく、特性だ 私は今ドキュメント読んでる 私はサボってない、今ビルド中
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
