アカウント名:
パスワード:
開発者が書かないでいる以上は、だれかがソースから解読してドキュメントを起こすしかないんだろうなあ。読めても書けない人はそういう貢献もあるねってことで。
ソース見れば実装はわかるけど、その背景や考え方がわからなかったりすることも多いんだよね。「この機能は旧バージョンとの互換のためのもので今後廃止される予定である。そのため、今後は新しい機能を使うべきである」、とか。
人のコードを触る業務が多いのですが、「背景の考え方」ってのが一番重要だと思ったり。実装されているコードってのは、やろうとしている(いた)ことの一側面を記述しているに過ぎないと思いますです。
すごく賛同します既存のソースコードからドキュメントを起こすという作業をしたことがあります
そのまま「こういう入力があればこういう動きをする」という部分は難なく書けるのですが「なぜその動きをするのか」は推測するしかないんですね
# で,とりあえず推測でテキトーな理由をでっち上げてお茶を濁すしかないんです...
あるある。特に困るのが何を目的としてこんな実装してんだよ、っての。しかもバグなのかどうなのか正解がさっぱりわからん系な。
その手のは詳細設計にも取りこぼされる事が多いから第三者に向けたソースコメントを書け、と指導してる
そのコメントが「こう動く」ってだけの内容ではなく、「○○と考えたので、□□のパターンで実装した」とかだと非常に助かる。
そして調べた結果をもとに簡単に設定するコマンドや設定画面作ると。
> そして調べた結果をもとに簡単に設定するコマンドや設定画面作ると。
それをバイナリ提供で費用請求するとタダ乗りとか批判をされる。でも、個別顧客相手への設定作業でお金をもらうなら文句は言われない。
うん、ドキュメント不足は雇用対策だ (違う?)
読めても書けない人はそういう貢献もあるねってことで。
問題は, ソースを読むためにはしばしば(というより殆どの場合かな?), 書いた人と同等以上の技量が必要になるってことでしょうか.
答えを見て解説を書くのと、答えを考えだすのとでは別の技能です。
そう言いながら食い散らかし続けて10年という事ですね・・・
昔から言われ続けているオープンソースの欠点の一つだもんね。みなボランティアでやると、各々やりたい事しかしない。面倒くさくてつまらないものは放って置かれるまま。
それはオープンソースではなくボランティアの欠点だろ。企業がフルタイムで開発者を雇用しているOSSも少なくないのに昔から言われ続けている印象操作の1つだね。
企業がフルタイムで開発者を雇用しているOSSも少なくないのに現実のドキュメントがプアなのはなんでだろうね。これまでの10年の現実を認められないなら今後10年もそのままかな。
印象操作?臍で茶が沸くっつーの。
>企業がフルタイムで開発者を雇用しているOSSも少なくないのに現実のドキュメントがプアなのはなんでだろうね。
プロプライエタリな商用製品(しかも高額)ならドキュメントがリッチだとでも?商用製品で問題にならないのは、販売元に直接問い合わせできるからに過ぎないですよ。
フルタイムで雇用していても、マンパワーとして不十分だとドキュメントより実装に人を回すから。だからプロジェクトによるというのが正しい。PostgreSQLとMySQLはドキュメントも割としっかり作ってある印象。
実際欲しいのはドキュメントより設定のサンプルだったりするんだけど。
>フルタイムで雇用していても、マンパワーとして不十分だとドキュメントより実装に人を回すから。
これはつまるところ↓こういう事。
>みなボランティアでやると、各々やりたい事しかしない。面倒くさくてつまらないものは放って置かれるまま。
つまり以下は否定されるわけだ。
>それはオープンソースではなくボランティアの欠点だろ。
ボランティア活動を使われる側としても、使う側としてもやった事がありますが、ボランティア活動って、使われる側の希望をそれほど重視しないんですよね。「何か貢献したい」という気持ちは大事にしつつも、何をするかは現場監督に任せるのが重要だったりする。災害後の後片付けなんかをやったことがあれば分かるけど、使われる側は兵隊に徹しないと全然捗らないんです。使う側の役割は、みんなに心地よく兵隊に徹してもらって作業を進めてもらう事だったりします。
FOSSの場合、そういう現場監督がなかなか存在しにくいところが、作業の方向性を決めにくい要因で、確かに欠点ではあるのですが、じゃあ実装者が足りているからお前はドキュメントを書けなんて、言ってくるFOSSプロジェクトなんてクソですからね。FOSSは義勇兵による活動というより、ならず者の寄せ集めという雰囲気が近いと思います。
たとえば?
実際10年以上続いてるプロジェクトで、ドキュメント少ないのって、なんですかね?
一般的なドキュメントは結構そろってきているような気がするのですが。Ubuntuは使わないのであまり知りませんが、ほんとに高度な内容であればプロプラでもマニュアルには載っていないような気がしますしサポートに問い合わせてくださいって対応も多いのでは?# そして、その設定はサポートされませんという回答が・・・TT
昔のOracleやHP-UXのような段ボール x 数十箱分のマニュアルの送付をご所望でしたか?そうですか・・・それは失礼しました。# あれはあれで、正誤表とのつき合わせや、物理的な質量など(主に腰が)大変だったよね
PostgreSQL http://www.postgresql.jp/document/ [postgresql.jp] MySQL http://dev.mysql.com/doc/ [mysql.com]
PHP http://php.net/manual/ja/ [php.net] Ruby
>企業がフルタイムで開発者を雇用しているOSSも少なくない
ヒント:フルタイムで雇用しているのは開発者
プロプライエタリな製品だからと言って、マニュアルが整備されてるとは限らないと思う。
一部の例外を提示ってやつですね。他のコメントにもある「そこだけ」ドキュメントが整理されているFOSSサイトを提示してさも整備されているような話に持っていこうとする。
だいたいにおいて整備されているのはプロプライエタリな製品という事実は変わらない。
ですね。プライベートでは作って無いです。。
コードは小説より面白いらしいからな。通勤電車のひと時、スマホでコードリーディングしながらニヤニヤするのも一興か。
そんなんめっちゃストレスたまるだけだわ。ソース読むときはファイル内、フィル間で、あちらに飛んだりこちらに飛んだり又戻ったり、変数や関数を検索したり。複数ウィンドウが開ける大画面とキーボードが無けりゃやってられん。
電車で読むときは、紙に縮小印刷して持っていく。行き戻りしやすいし、複数のページを同時に眺められる。検索が出来ないのが残念だが。
C#やVB.NETだとソース読むの楽なんだが、rubyやC++とかだとそうもいかねえんだよね動的言語って本当に生産性が高いのかね呼び出し元も見つけられないし、ジャンプもできない。入力補完も効かない。疑問だわ
そろそろどっかの天才が「ソースを食わせるとドキュメントを吐き出してくれるソフトウェア」というのを発明してくれないものか。
ドキュメントと一言で扱われることが多いけど、階層や想定読者で違うよね。
このコメント [srad.jp]で言われているような、ポリシーや方針みたいな大雑把なものから、動作オプションの影響範囲と差、さらに細かくは関数の引数の意味、みたいなものまで。
ドキュメントを出せ、は「俺が知りたいことが 1ページで書いてある資料をだせ」なことも多くて、結局 google だったりする。 (私はお前のおかあさんじゃない)
C++にソースからクラス相関図を自動生成してくれるDoxygenというのがあるけど手でUMLを書くことを考えたらものすごい進歩だと思う#ってそういう話じゃないか
あれみても結局「スタートはどこ?」と放り出される感が半端ない。
http://www.cryptopp.com/docs/ref/ [cryptopp.com]
いや、あるだけいいんだけど。。結局はテストコードとか、実装を追うことに。
こういうアプローチは他コメント [srad.jp]のtex のシステム [wikipedia.org]の話もあるけど、別ドキュメントを生成するんばかりでなくて、そのまま printf() で出力すれば、printf() で出力できる形に exe に取り込んでくれれば いいんでないか?
時代が変わってメモリもHDDも安くなったんだから、--help とか --version で簡単に説明が得られるやりかたの伸張として、--source とやるとソースが出てくる、--documents でドキュメントが出てくる、なんてのもありだと思うが。
ソースにコメントを入れてくれ! と言いたい。特にトリッキーな技を使っていたりすると、挫けてしまう。あとわかりやすい変数名をつけてくれ。お願いだ。
読めても書けない人って本当に存在するのか?自分がやりたくないことを他人に押し付けたいがための方便じゃないか?ある時点では書けなくても、読んでいれば書いてみたくなって、そのうち書くだけの人になる。
だから、現状があるんだと思うわけだが。
英語が読めるけど書けない人とかたくさんいると思うが
その人がどうやってドキュメント書くんだ?
目的語を省略しすぎてバカになってないか…?もとの話に戻ると、コードは読めるけどコードを書くことはできないひとにドキュメントを書いてもらえばいいんじゃないかという話だったわけだ。つまり、#2654262 は「英語が読めるけど英語が書けない日本人がどうやって日本語解説を書くんだ?」と言ってることになるわけだが、これはむしろそれのどこに無理があるというのかと問い返してみたいなあ。
「書く」ってのはこの場合、FOSSの各種プロダクツに貢献できるレベルのスキルを持っていて、実際に自分のコードが使われている(FOSSに書いている)ような人を指すんでは?
なんとか動く、というレベルのプログラムを書ける人は大勢居て、そういう人はFOSSにコードが採用されているようなスキルのある人達が書いた洗練されたコードも大体理解できる。
でもコードが世界中の開発者の目に晒され、あれこれ評価をうけるという試練を耐えきるレベルの上質なコードを書ける人はそう多くない。
「使い方がわからなければソースを読め」とは、自分ではやるし、プログラムソースを読めそうな人にはそういうけれど、そうではない圧倒的多数の人に対しては「市販の売り物を使え」って言いますね。
だって、イデオロギーの問題で無理矢理オプソを使わせるより、もうちゃんとしたサポート窓口のある製品を使わせた方が楽だし。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
未知のハックに一心不乱に取り組んだ結果、私は自然の法則を変えてしまった -- あるハッカー
ソースから (スコア:2, 興味深い)
開発者が書かないでいる以上は、だれかがソースから解読してドキュメントを起こすしかないんだろうなあ。
読めても書けない人はそういう貢献もあるねってことで。
Re:ソースから (スコア:3, 興味深い)
ソース見れば実装はわかるけど、その背景や考え方がわからなかったりすることも多いんだよね。
「この機能は旧バージョンとの互換のためのもので今後廃止される予定である。そのため、今後は新しい機能を使うべきである」、とか。
Re:ソースから (スコア:1)
人のコードを触る業務が多いのですが、「背景の考え方」ってのが一番重要だと思ったり。
実装されているコードってのは、やろうとしている(いた)ことの一側面を記述しているに過ぎないと思いますです。
Re:ソースから (スコア:2, すばらしい洞察)
すごく賛同します
既存のソースコードからドキュメントを起こすという作業をしたことがあります
そのまま「こういう入力があればこういう動きをする」という部分は難なく書けるのですが
「なぜその動きをするのか」は推測するしかないんですね
# で,とりあえず推測でテキトーな理由をでっち上げてお茶を濁すしかないんです...
Re: (スコア:0)
あるある。特に困るのが
何を目的としてこんな実装してんだよ、っての。
しかもバグなのかどうなのか正解がさっぱりわからん系な。
その手のは詳細設計にも取りこぼされる事が多いから
第三者に向けたソースコメントを書け、と指導してる
Re:ソースから (スコア:1)
そのコメントが「こう動く」ってだけの内容ではなく、「○○と考えたので、□□のパターンで実装した」とかだと非常に助かる。
Re:ソースから (スコア:2, 興味深い)
そして調べた結果をもとに簡単に設定するコマンドや設定画面作ると。
Re: (スコア:0)
> そして調べた結果をもとに簡単に設定するコマンドや設定画面作ると。
それをバイナリ提供で費用請求するとタダ乗りとか批判をされる。
でも、個別顧客相手への設定作業でお金をもらうなら文句は言われない。
うん、ドキュメント不足は雇用対策だ (違う?)
Re:ソースから (スコア:1)
問題は, ソースを読むためにはしばしば(というより殆どの場合かな?), 書いた人と同等以上の技量が必要になるってことでしょうか.
Re: (スコア:0)
答えを見て解説を書くのと、答えを考えだすのとでは別の技能です。
Re: (スコア:0)
そう言いながら食い散らかし続けて10年という事ですね・・・
Re:ソースから (スコア:4, 興味深い)
昔から言われ続けているオープンソースの欠点の一つだもんね。
みなボランティアでやると、各々やりたい事しかしない。面倒くさくてつまらないものは放って置かれるまま。
Re: (スコア:0)
それはオープンソースではなくボランティアの欠点だろ。
企業がフルタイムで開発者を雇用しているOSSも少なくないのに昔から言われ続けている印象操作の1つだね。
Re: (スコア:0)
企業がフルタイムで開発者を雇用しているOSSも少なくないのに現実のドキュメントがプアなのはなんでだろうね。
これまでの10年の現実を認められないなら今後10年もそのままかな。
印象操作?臍で茶が沸くっつーの。
Re:ソースから (スコア:1)
>企業がフルタイムで開発者を雇用しているOSSも少なくないのに現実のドキュメントがプアなのはなんでだろうね。
プロプライエタリな商用製品(しかも高額)ならドキュメントがリッチだとでも?
商用製品で問題にならないのは、販売元に直接問い合わせできるからに過ぎないですよ。
Re: (スコア:0)
フルタイムで雇用していても、マンパワーとして不十分だとドキュメントより実装に人を回すから。
だからプロジェクトによるというのが正しい。
PostgreSQLとMySQLはドキュメントも割としっかり作ってある印象。
実際欲しいのはドキュメントより設定のサンプルだったりするんだけど。
Re: (スコア:0)
>フルタイムで雇用していても、マンパワーとして不十分だとドキュメントより実装に人を回すから。
これはつまるところ↓こういう事。
>みなボランティアでやると、各々やりたい事しかしない。面倒くさくてつまらないものは放って置かれるまま。
つまり以下は否定されるわけだ。
>それはオープンソースではなくボランティアの欠点だろ。
Re:ソースから (スコア:1)
ボランティア活動を使われる側としても、使う側としてもやった事がありますが、
ボランティア活動って、使われる側の希望をそれほど重視しないんですよね。
「何か貢献したい」という気持ちは大事にしつつも、何をするかは現場監督に任せるのが重要だったりする。
災害後の後片付けなんかをやったことがあれば分かるけど、使われる側は兵隊に徹しないと全然捗らないんです。
使う側の役割は、みんなに心地よく兵隊に徹してもらって作業を進めてもらう事だったりします。
FOSSの場合、そういう現場監督がなかなか存在しにくいところが、作業の方向性を決めにくい要因で、
確かに欠点ではあるのですが、じゃあ実装者が足りているからお前はドキュメントを書けなんて、
言ってくるFOSSプロジェクトなんてクソですからね。
FOSSは義勇兵による活動というより、ならず者の寄せ集めという雰囲気が近いと思います。
Re: (スコア:0)
たとえば?
Re: (スコア:0)
実際10年以上続いてるプロジェクトで、ドキュメント少ないのって、なんですかね?
一般的なドキュメントは結構そろってきているような気がするのですが。
Ubuntuは使わないのであまり知りませんが、ほんとに高度な内容であれば
プロプラでもマニュアルには載っていないような気がしますし
サポートに問い合わせてくださいって対応も多いのでは?
# そして、その設定はサポートされませんという回答が・・・TT
昔のOracleやHP-UXのような段ボール x 数十箱分のマニュアルの送付をご所望でしたか?
そうですか・・・それは失礼しました。
# あれはあれで、正誤表とのつき合わせや、物理的な質量など(主に腰が)大変だったよね
PostgreSQL
http://www.postgresql.jp/document/ [postgresql.jp]
MySQL
http://dev.mysql.com/doc/ [mysql.com]
PHP
http://php.net/manual/ja/ [php.net]
Ruby
Re: (スコア:0)
>企業がフルタイムで開発者を雇用しているOSSも少なくない
ヒント:フルタイムで雇用しているのは開発者
Re: (スコア:0)
プロプライエタリな製品だからと言って、マニュアルが整備されてるとは限らないと思う。
Re: (スコア:0)
一部の例外を提示ってやつですね。
他のコメントにもある「そこだけ」ドキュメントが整理されているFOSSサイトを提示してさも整備されているような話に持っていこうとする。
だいたいにおいて整備されているのはプロプライエタリな製品という事実は変わらない。
Re: (スコア:0)
ですね。プライベートでは作って無いです。。
Re: (スコア:0)
コードは小説より面白いらしいからな。
通勤電車のひと時、スマホでコードリーディングしながらニヤニヤするのも一興か。
Re:ソースから (スコア:2, 興味深い)
そんなんめっちゃストレスたまるだけだわ。
ソース読むときはファイル内、フィル間で、あちらに飛んだりこちらに飛んだり又戻ったり、変数や関数を検索したり。
複数ウィンドウが開ける大画面とキーボードが無けりゃやってられん。
電車で読むときは、紙に縮小印刷して持っていく。行き戻りしやすいし、複数のページを同時に眺められる。
検索が出来ないのが残念だが。
Re: (スコア:0)
C#やVB.NETだとソース読むの楽なんだが、rubyやC++とかだとそうもいかねえんだよね
動的言語って本当に生産性が高いのかね
呼び出し元も見つけられないし、ジャンプもできない。入力補完も効かない。
疑問だわ
Re: (スコア:0)
そろそろどっかの天才が「ソースを食わせるとドキュメントを吐き出してくれるソフトウェア」というのを発明してくれないものか。
Re:ソースから (スコア:3, すばらしい洞察)
ドキュメントと一言で扱われることが多いけど、階層や想定読者で違うよね。
このコメント [srad.jp]で言われているような、ポリシーや方針みたいな
大雑把なものから、動作オプションの影響範囲と差、さらに細かくは
関数の引数の意味、みたいなものまで。
ドキュメントを出せ、は「俺が知りたいことが 1ページで書いてある資料をだせ」なことも
多くて、結局 google だったりする。 (私はお前のおかあさんじゃない)
Re:ソースから (スコア:2)
Re: (スコア:0)
C++にソースからクラス相関図を自動生成してくれるDoxygenというのがあるけど
手でUMLを書くことを考えたらものすごい進歩だと思う
#ってそういう話じゃないか
Re:ソースから (スコア:1)
あれみても結局「スタートはどこ?」と放り出される感が半端ない。
http://www.cryptopp.com/docs/ref/ [cryptopp.com]
いや、あるだけいいんだけど。。
結局はテストコードとか、実装を追うことに。
Re:ソースから (スコア:1)
こういうアプローチは他コメント [srad.jp]のtex のシステム [wikipedia.org]の話も
あるけど、別ドキュメントを生成するんばかりでなくて、そのまま printf() で出力すれば、
printf() で出力できる形に exe に取り込んでくれれば いいんでないか?
時代が変わってメモリもHDDも安くなったんだから、
--help とか --version で簡単に説明が得られるやりかたの伸張として、
--source とやるとソースが出てくる、--documents でドキュメントが
出てくる、なんてのもありだと思うが。
お願い (スコア:0)
開発者が書かないでいる以上は、だれかがソースから解読してドキュメントを起こすしかないんだろうなあ。
読めても書けない人はそういう貢献もあるねってことで。
ソースにコメントを入れてくれ! と言いたい。
特にトリッキーな技を使っていたりすると、挫けてしまう。
あとわかりやすい変数名をつけてくれ。
お願いだ。
Re: (スコア:0)
読めても書けない人って本当に存在するのか?
自分がやりたくないことを他人に押し付けたいがための方便じゃないか?
ある時点では書けなくても、読んでいれば書いてみたくなって、そのうち書くだけの人になる。
だから、現状があるんだと思うわけだが。
Re: (スコア:0)
英語が読めるけど書けない人とかたくさんいると思うが
Re: (スコア:0)
その人がどうやってドキュメント書くんだ?
Re: (スコア:0)
目的語を省略しすぎてバカになってないか…?
もとの話に戻ると、コードは読めるけどコードを書くことはできないひとにドキュメントを書いてもらえばいいんじゃないかという話だったわけだ。つまり、#2654262 は「英語が読めるけど英語が書けない日本人がどうやって日本語解説を書くんだ?」と言ってることになるわけだが、これはむしろそれのどこに無理があるというのかと問い返してみたいなあ。
Re: (スコア:0)
「書く」ってのはこの場合、FOSSの各種プロダクツに貢献できるレベルのスキルを持っていて、
実際に自分のコードが使われている(FOSSに書いている)ような人を指すんでは?
なんとか動く、というレベルのプログラムを書ける人は大勢居て、そういう人はFOSSにコードが採用されているような
スキルのある人達が書いた洗練されたコードも大体理解できる。
でもコードが世界中の開発者の目に晒され、あれこれ評価をうけるという試練を耐えきるレベルの上質なコードを書ける人はそう多くない。
Re: (スコア:0)
「使い方がわからなければソースを読め」とは、自分ではやるし、プログラムソースを読めそうな人にはそういうけれど、そうではない圧倒的多数の人に対しては「市販の売り物を使え」って言いますね。
だって、イデオロギーの問題で無理矢理オプソを使わせるより、もうちゃんとしたサポート窓口のある製品を使わせた方が楽だし。