コードは「何をするか」しか教えてくれない

ITnews 編集部 / 2ヶ月

この記事は、Marc Brooker氏によって公開された記事の翻訳転載です。

この記事をPICKする

hatenabookmark
山本 聡

2ヶ月前

>ほとんどのソフトウェアエンジニアは、学校を卒業したときに、ドキュメンテーションは自分より下のレベルの人がする仕事(テックライターの仕事)だと思っているようです。

20年も仕事現場で最前線でがんばっていると思うんだけど。ますますその思いは強くなるばかりだけどね。
ドキュメントなんて、ビルドエラーも不具合もださないんだから、クリティカルなスキルが必要な仕事じゃないから、プログラマより下のレベルの人がする仕事で間違いないんだよ。プログラマはもっと価値を叩き出す重要な仕事をこなさないと非効率。

ただ記事には同意するとこもあるから、コードで、あるいはコード内のコメントなどで何を目的として実装しているかを表せるように心がけたりします。

ま。今はチケット管理するからチケット上のやり取りとコミットに残るチケット番号で十分だったりしますね。過去ログをたどったりする場面もそんなにないし、そのために文章を清書するなんてコストかけるのはおかしな話。

なので、
>ドキュメントは必ず保管しておくようにしましょう。どこか安全な場所に保管してください。
これは馬鹿げた理論ですかね。

プログラミングにおいて、最重要なドキュメントはコード。
他のドキュメントの優先度は低く、
また、ドキュメントは単なるコミュニケーションツールなので、チケット管理システムでコミュニケーションが正しく行われているなら、「ドキュメント」そのものに力を入れる必要なんてないよ。

それが爆速開発のために必要なこと。
ドキュメント書いて日本語の敬語がおかしいから修正してとかいうドキュメントレビューして、プログラマがコード書いているべき時間にドキュメント書いているなんて、馬鹿らしくて低速開発でやってられなくなる気分です。
清水 風音

2ヶ月前

「メンテナンス大変」「コードが正」と、開発現場ではドキュメントがとかく軽視されがちです。ただ、過去の意図を汲み取り、正しくプログラムするためには、「どのように」その仕様を決定したかのドキュメンテーションがやはり重要。うちでもプルリクはテンプレ化して、過去の決定事項は徹底的に残すようにしています。
nekotekijoshi

2ヶ月前

pickしました
中野 友貴

2ヶ月前

Pickしました
秋田 法世

2ヶ月前

Pickしました
この記事は、Marc Brooker氏によって公開された記事の翻訳転載です。
appstore
googleplay
会員登録
URLからPICKする

会員登録して、もっと便利に利用しよう

  • 1.

    記事をストックできる
    気になる記事をPickして、いつでも読み返すことができます。
  • 2.

    新着ニュースをカスタマイズできます
    好きなニュースフィードをフォローすると、新着ニュースが受け取れます。