JavaScriptのコメントは不要か？ | POSTD
コード中にコメントを書くべきでしょうか？ 是が非でも避けるべきでしょうか？ それとも控えめに書けばいいでしょうか？ 開発者たちはそれぞれ、ソフトウェアを開発する際にどのように、そしてどんな時にコメントを書くかについて、独自の考え方を持っています。この記事では私の意見を述べますが、これが誰にも当てはまるというわけではありません。 なお、関数型プログラミングまたはオブジェクト指向プログラミングの原則に則ってJavaScriptで書かれたソフトウェアに絞った上で、私の意見を述べることにします。 コメントと保守性 この記事では、保守性のあるコードを書く場合について考えます。つまり、以下のようなコードです。 簡単に理解できる 簡単に拡張できる 簡単にデバッグできる 簡単にテストできる 保守性のあるコードには、大量のコメントが必要でしょうか？ 明確に書かれたコードであるならば、大量のコメントは不要だと
アジャイル開発者の習慣―acts_as_agile：第4回 ドキュメントを大切にする｜gihyo.jp … 技術評論社
ソースがドキュメントだ。バグも完全に記述されている。 ――まつもとゆきひろ[1] はじめに 本連載ではアジャイル開発を「アジャイルに開発する人たち（アジャイル開発者）が開発するからアジャイル開発」と考え、アジャイル開発者に必要なスキルを磨くための習慣を紹介しています。 これまでの3回を費して紹介した「フィードバックを重視する」「仕組みを育てる」「スケール間に連続性を築く」といった習慣は、チームによるシステム開発の現場でアジャイルにプログラムを書くことを重視したものでした。 しかし、これでは開発対象となるシステムを構成する2つの要素のうち主に1つしか説明していません。2つの要素とは、プログラムとドキュメントです。今回は、これまであまり触れてこなかった、2つの要素のうちの1つであるドキュメントに関する習慣を紹介します。 そのためにまず、アジャイル開発者にとってのドキュメントの位置づけを説明
なぜドキュメントを書かない？ - ある組込みソフトエンジニアの日記
久しぶりに『ジョエル・オン・ソフトウェア』を読んだ。Amazon で調べたら、最近、この本の続編である『モア・ジョエル・オン・ソフトウェア』が出たようだ。 ジョエル・オン・ソフトウェアの著者である Joel Spolsky はソフトウェア業界での豊かな経験を持つ開発者で、彼のウェブログ "Joel on Software" はプログラマ向けサイトとしては最も人気のあるものの一つで、彼はマイクロソフトの開発者だったころ Microsoft Excel 等多くの有名なソフトウェア製品の開発に携わった。 彼がブログで記事にしたことをまとめた最初の本が『ジョエル・オン・ソフトウェア』である。もともとはブログの記事であり。アメリカ人でないとわからないようなスラングや引用（例えばジョージ・ブッシュ大統領の口癖 Not gonna do it! 「それをやるつもりはない」等）がふんだんにちりばめられてお
Javadoc ドキュメンテーションコメントの書き方 - Qiita
出展: プログラム内のコメントの書き方 | 天才まくまくノート はじめに（モチベーション） こんな話があります。あるソフトウェア企業が一人の技術者の採用を決めました。その決め手となった理由は、「公開しているオープンソースソフトウェアのドキュメントが素晴らしかったから」です。彼らは、作成されたドキュメントを見ただけで、その人には技術力がある、一緒に働いて欲しいと判断したのです。 ある国の言語を学ぶために読み書きの練習が必要であるのと同様に、コーディング技術をつけるには、多くの良質なコードを読み、多くのコードを書くことが必要です。設計ドキュメントを書くのも同じことです。日頃から分かりやすいドキュメントを書く鍛錬を怠らず、長年の経験を積んでいかなければ、良質なドキュメントを書く力は身に付きません。今日からドキュメンテーションコメントをバリバリ書いて、ドキュメンテーション力を付けていきましょう。
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
In defense of JSDoc
わかりやすい技術文書へのアプローチ：技術文書の「書き方」－共通のポイントと各種文書への応用－