プログラマーがドキュメントを書かない理由

この記事は、著者の許可を得て配信しています。 Why programmers don’t write documentation 最近ではずっとコードのドキュメンテーションに関連した記事を書いていたので、当然、私のMediumのおすすめ記事には「開発者がドキュメントを書かない本当の理由」という記事が表示されるようになりました。この記事では、ドキュメントを書くための優れたツールがないことが、ソフトウェアエンジニアが自分の作業や判断をドキュメンテーションする意欲を失わせる最大の原因について書いています。 私は普段、特定の記事を批判したりはしませんが、この記事には怒りを覚えました。このライターは図解ツールについていくつかメリットに関して述べてはいますが、全体的に誤解を招くような内容になっており、この重要な問題をより分かりにくくさせています。2つの図解ツールを比較して、どちらも不十分なツールである

[Magicant]

訳が所々怪しいのはともかく、ドキュメントを書くのがコーディングよりずっと難しいのは事実

[enhanky]

外部仕様はユーザーマニュアルとして書いとけ。内部仕様はコードに丁寧なコメントつけとけばまあ困らない。コードはドキュメントなので。

[satorhyum]

プログラム書くのは楽しいけどドキュメント書くのはめんどくさいからだよ（本文読んでない

[atsushifx]

プロジェクトにドキュメントを書く時間をとってあるか？

[degucho]

コードは全てを表してるので必要なのはなぜこの仕様になったかという経緯ですよ

[hiro_curry]

プログラムの動きを説明するのにベストな言語はプログラミング言語だからね。

[nearlyinhuman]

SIerをバカにする割にはこういう作業を避けるんだよなぁウェブ系エンジニアは… ITのことわからない別業種の人に説明できるから彼らが仕事取ってくるんだろうに

[imwks]

例えがアレだけど、英文を完全に日本語訳できないしね。ニュアンスは伝わるけど細部に渡って翻訳しても意味がわからなかったりする。プログラムにおけるドキュメントもそういう感じはする

[satoko_szk]

ドキュメント、書くよ？ ソースコードは、例えるなら、表札までわかるレベルまで拡大した地図。市区町村レベルで俯瞰して方式検討する必要のある時もあるので、必要に応じて必要なレベルのドキュメントを用意する。

[yarumato]

“文書記述はプロセスの一部になるべき。有効だった施策：コードを書く前に（自分が何をしようとしているのか）書く。実際の実装を詳細に説明せず、選択事項とその理由を説明する。検索可能にする。変更を追跡する”

[tmurakam]

ドキュメント書く能力とコードを書く能力には結構相関があると思ってる。有能なプログラマはだいたいドキュメント書くのもうまい。逆にドキュメント書けないプログラマのコードはだいたいひどい。

[Amigomr]

「ドキュメント」の定義がわからんが、設計書もなく（あってもメンテされておらず）、コードにコメントも一切ない状態で、過去のコミットログやチケットから経緯を探る考古学的作業を減らすべきというなら同意する

[rryu]

関数やメソッドレベルのドキュメントのことならコード見るだけで終わるという矛盾を抱えつつ「この表現で繰り返しと気付いてもらえるだろうか」みたいな謎の苦労をするところだと思う。

[threetea0407]

> 複雑なコードにコメントを求めても無駄（略）。なぜなら、コードで明確に表現できなかった人たちに、今度は英語で明確に表現することを期待しているからです。

[btron]

そもそもちゃんと設計してなくて、流れで書く人が結構いるので、コード自体がドキュメントにしにくいものになってると言うのもあるかな。大体、きれいにドキュメントやコードを書いてもそれ自体は評価されんし・・。

[Keisuke69]

そりゃ単純にコードだけ書いてたいからじゃないの

[frontline]

場合によっては食事の方法を教えるのに文章で箸の持ち方から書かないといけない、みたいな難しさは有ると思う。

[i-think-so-too]

書けないだけなのに（あえて）書かないと言いわけする人も多い

[sjn]

ドキュメントを正しく評価してるのかは気にしてる。最近特に思わされることが多い。

[harumomo2006]

勝手にコロコロ仕様を変えられて編集が追い付かないんだよ

[capriccio-bwv-993]

プログラム自体がドキュメントだからです (´・ω・｀)

[yoiIT]

雰囲気でプログラム書いてるやつはドキュメント作れないよね。

[mysql8]

歩く仕様書と呼び給え

[TokyoWorker]

プログラマーじゃなくても、設計業務してる人全員に共通の考え方

[fikah]

ドキュメントはどれだけ頑張って書いても絶対に後々更新されなくなって腐るから書く気がおきない

[w1234567]

良いドキュメントを書くためには相手の気持ちを想像する力が必要なんだけど、そういう能力が未熟もしくは欠落してる奴がプログラマーになるからだよ

[kotaponx]

書いても誰も読んでくれないけどね。まぁ、ドキュメントは保守する未来の自分の為に書くのだけど。

[alt-native]

仕様を言語化できない人が プログラミングできるわけない。面倒なのは 顧客に提出するために、そのドキュメントの体裁を整えること。それはエンジニアじゃなくたって面倒。

[murasen]

第2弾はマネージャがドキュメントを書かせない理由で頼むな

[Dragoonriders]

なぜこう実装したかなんて仕様とユースケースを網羅した上でその軽重を見てこうしようって判断したかを書かねば意味ないのだから、はっきり言ってめんどくさいんだよ。どこかパラメータが変われば全部変わるのでな。

[nida3001]

ドキュメントを書くのは本当に難しいしツラいお仕事なので、ドキュメント有害論が人気を集めてしまうわけよ。

[burabura117]

コードが全てを表しているからドキュメント書かないみたいなコメントがスターを集めてて恐ろしくなった

[ntstn]

コードはドキュメント。必要なら設計者が作るといい。

[hayashikousun]

工数見積もりの時にドキュメントを書く時間を誰も計算に入れていないのが最大の理由。

[question20170711]

プログラマーに関わらずドキュメントを残すのには一種の才能が必要だと思う。

[tianbale-battle]

ソースに書いてるものをわざわざ文章で書きたくない気持ちは超わかる。ドキュメントが全ての現場で必要かと言われると微妙だけど、作らないならソースの管理だけはちゃんとやってほしい。

[napsucks]

書いたものがドキュメントなんだよ！

[TETOS]

金にならないから

[dollarss]

“なぜなら、明確に書くことが本当に本当に難しいからです。”こう明記してくれると救われた気持ちになるね。だって本当に難しいもん…