記事へのコメント31

    • 人気コメント
    • 新着コメント
    vine_hate vine_hate ドキュメント

    2022/04/22 リンク

    その他
    Itisango Itisango 社内のSWEにあまり実装経験が無いようなシステム/事業ドメインのコアでいろいろなSWEが触るようなシステム/世間一般に情報が無い社内独自のシステム

    2022/03/19 リンク

    その他
    ema_hiro ema_hiro わかるなーと思いつつ、こういうのも試行錯誤なんだよなー、というお気持ち。ちょうどいい塩梅が難しい。

    2021/08/16 リンク

    その他
    clockwork9 clockwork9 最適なドキュメントの詳細度は組織次第。適切なスキルかつ同一文化圏のエンジニアが揃い、プルリクエストのレビューが機能しており、かつ完全内製の自社サービスの前提なら記事に同意。

    2021/08/16 リンク

    その他
    vndn vndn スナップショットと割り切るところはいいとしても、読んだ人が直すって手法に不安が残る。読んだ人が気づいた乖離のみ直されるわけで、結果どの時点のスナップショットとしても正しくなくなるように思う。

    2021/08/16 リンク

    その他
    sigwyg sigwyg ドキュメントには設計や実装理由を書けば陳腐化しにくい、てのは確かに/“ソフトウェアエンジニア(以下SWE)” SEじゃないのん?Wが気になって夜も眠れな(ry

    2021/08/16 リンク

    その他
    tg30yen tg30yen >スナップショットだと割り切る これでいいと思う。「この時点ではこうだった」は現在のシステムを理解する上でも十分有用だよ。常に最新にアップデートされていなければ役に立たないなんてことはない。

    2021/08/16 リンク

    その他
    pmint pmint ドキュメントが実装に合わせる側(主従関係の従)なのかな。「コメントの集まり」って感じか。本来は実装に守らせることを書くものだけど。/ 「コードに書いてあることは書かない」と言えば分かりやすくなると思う。

    2021/08/16 リンク

    その他
    kagerou_ts kagerou_ts スナップショットと割り切るのは、原則的には今と違った情報乗せてしまっていてだめかもしれないけど、どのみち更新されず古くなる率高いのだから現実的な対応なのかも。そこが一番コストバランスよさそうとは

    2021/08/16 リンク

    その他
    tpircs tpircs 文中にも記載あるけど、ドキュメントの肝は抽象化だよね。抽象的なコードを書くのは難しいので図や絵で表現する。そのほうが人類には理解しやすい。なので設計書は文章もいいんだけど図とか絵が大事だと思ってる。

    2021/08/16 リンク

    その他
    ledsun ledsun 2010年頃までは受託開発で、ドッチファイルに挟んだドキュメントを納品していた。あれは、ソフトウェアを理解する助けにはなってなかったろうなあ…

    2021/08/16 リンク

    その他
    diveintounlimit diveintounlimit 抽象度が高すぎて、これに則って書かれた「ドキュメント」を読んで何かを理解できる気がしない

    2021/08/16 リンク

    その他
    shioki shioki “ドキュメントを書く理由は人によって様々かもしれませんが、僕の場合は「ドキュメントにより、そのシステムをスムーズに理解できて、コードの読み書きを効率的にできるようになるため」です”

    2021/08/16 リンク

    その他
    KazuoLv1 KazuoLv1 ソースがドキュメントです。と真顔で言われて過去に辛い思いをしたなあ。インターフェースと簡単なサンプルあるだけで全然違うのに。

    2021/08/16 リンク

    その他
    hamamuratakuo hamamuratakuo ドキュメントの読者対象はプログラマーを想定して書く。必要な設定情報はもちろんのこと、予算の制約などで削ったり無理している部分もあれば全てネタばらしするかんじ。コードが読めないアホには紙ペラ1枚で十分?

    2021/08/16 リンク

    その他
    ed_v3 ed_v3 可能な限りjsdocとかコード内に書けるもののみに留めてる。それ以上必要になったら全部ARCHITECTURE.mdに書くように最近はしてる。そして必要に応じてコード内コメントでARCHITECTURE.mdのセクションにリンク貼って更新忘れ防止

    2021/08/16 リンク

    その他
    w1234567 w1234567 当時の人がどういう意図で設計を進めていたのかが分かるから多少古くても問題ないよ。というか、コロナ化のリモートワークではドキュメントいらない勢はトラブルメーカーになってる人が多いからもう少し自省してくれ

    2021/08/16 リンク

    その他
    jacoby jacoby (コード担当者が他者とコミュニケーションするための)外部仕様書はコードと一致してないと仕様不良とプログラム不良の判断できなくなる。内部仕様ならドキュメントよりコード読めになっても仕方ないとは思う。

    2021/08/16 リンク

    その他
    peketamin peketamin "今回はソフトウェアやシステムの内部構造を説明するドキュメントについての話です"/受託とtoC向け自社製品では事情も違うと思うし、いいと思います。

    2021/08/16 リンク

    その他
    korilog korilog 少なくともその時点で正しいドキュメントはあったほうがいい。なんでこうなっているのかをコードの歴史から推測するよりドキュメント読む方が早いし。そもそもコードを読む理解を助けるものを書くイメージ。

    2021/08/15 リンク

    その他
    ardarim ardarim ドキュメントの定義が世間一般と乖離している気がする。一般的にソフトウェア開発におけるドキュメントとは設計資料であって、説明資料、説明書ではない。ROIとか言ってる時点で見ているものが違う

    2021/08/15 リンク

    その他
    strow0343 strow0343 そのメンテ意識なら基本的に実装見に行くのが一番早い。ドキュメントは実装の理解の補助程度に落ち着くと思う。

    2021/08/15 リンク

    その他
    moromoro moromoro スナップショットと割り切ってしまい、ベンダ納品ドキュメントをメンテせずに動いてるサービスが多い

    2021/08/15 リンク

    その他
    hogetahogeko hogetahogeko 『ドキュメントに詳細を書かない。スナップショットだと割り切る、その代わり、そのドキュメントを読んだ人が古くなった内容に気づいたときは積極的に直してもらう』

    2021/08/15 リンク

    その他
    a-kuma3 a-kuma3 「スナップショットと割り切る」はダメだろう。そもそもがコードだけじゃキツイからドキュメント欲しい、なのに、コードと一致してないドキュメントはゴミ以上に害悪。RoIなんて言ってないでコストをかけろ、ってこと

    2021/08/15 リンク

    その他
    tokg tokg

    2021/08/15 リンク

    その他
    nunulk nunulk "読む人がほぼほぼ知ってそうなレベル、わかりきってるレベルから書き始めます。"

    2021/08/15 リンク

    その他
    hitotakuchan hitotakuchan ドキュメントの無いソフトウェアはいずれ必ず負債になる

    2021/08/15 リンク

    その他
    naskin naskin ]

    2021/08/15 リンク

    その他
    kenzy_n kenzy_n ちゃんと意図の伝わるものが望ましい

    2021/08/15 リンク

    その他

    人気コメント算出アルゴリズムの一部にヤフー株式会社の「建設的コメント順位付けモデルAPI」を使用しています

    関連記事

    ソフトウェアドキュメント作法 - maru source

    こんにちは丸山@h13i32maruです。つい先日、devchat.fmというポッドキャストに出演して、「ドキュメント...

    ブックマークしたユーザー

    • zxcvbnmtacashi2022/06/30 zxcvbnmtacashi
    • hasefumi232022/04/30 hasefumi23
    • suji_ski2022/04/22 suji_ski
    • updjop2022/04/22 updjop
    • vine_hate2022/04/22 vine_hate
    • dmizuno552022/04/22 dmizuno55
    • Itisango2022/03/19 Itisango
    • tsumuchan2022/01/22 tsumuchan
    • twoten210kaku2022/01/16 twoten210kaku
    • knj29182022/01/06 knj2918
    • usadamasa2021/10/19 usadamasa
    • ksugaa2021/10/10 ksugaa
    • kyo_ago2021/09/15 kyo_ago
    • heatman2021/09/14 heatman
    • karuakun2021/09/08 karuakun
    • hamaco2021/09/03 hamaco
    • dhesusan46492021/09/03 dhesusan4649
    • hyperdb2021/09/01 hyperdb
    すべてのユーザーの
    詳細を表示します

    同じサイトの新着

    同じサイトの新着をもっと読む

    いま人気の記事

    いま人気の記事をもっと読む

    いま人気の記事 - テクノロジー

    いま人気の記事 - テクノロジーをもっと読む

    新着記事 - テクノロジー

    新着記事 - テクノロジーをもっと読む

    同時期にブックマークされた記事