Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 11659] ファイルの概要

このコミットは、Go言語のドキュメントおよびコードコメントにおける「simply」という単語の過剰な使用を修正することを目的としています。特に、読者がその内容を「単純」ではないと感じる可能性があるにもかかわらず、コードやアクションが単純であると主張している箇所からこの単語を削除しています。これにより、ドキュメントのトーンを改善し、読者に対してより正確で、誤解を招かない表現にすることが意図されています。

コミット

commit ae7497bda63382930cf729803435fc455980c9dc
Author: Russ Cox <rsc@golang.org>
Date:   Mon Feb 6 13:34:35 2012 -0500

    doc: remove overuse of simply
    
    Specifically, remove simply where it is claiming that the
    code or the action to be carried out is simple, since the
    reader might disagree.
    
    R=golang-dev, bradfitz, gri
    CC=golang-dev
    https://golang.org/cl/5637048

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/ae7497bda63382930cf729803435fc455980c9dc

元コミット内容

このコミットは、Go言語のドキュメントとコードコメントから「simply」という単語の過剰な使用を削除することを目的としています。具体的には、コードや実行されるアクションが単純であると主張している箇所から「simply」を削除しています。これは、読者がその内容を単純ではないと感じる可能性があるためです。

変更の背景

技術文書やコードコメントにおいて「simply」という単語を使用することは、書き手にとっては内容が簡単であるという意図を伝えるものですが、読み手にとっては異なる受け取られ方をすることがあります。特に、その内容が読み手にとって実際には単純ではない場合、この単語は以下のような問題を引き起こす可能性があります。

  1. 読者への威圧感: 読み手が内容を理解するのに苦労している場合、「simply」という言葉は、読み手の理解力不足を暗に示唆しているように感じさせ、不快感や劣等感を与える可能性があります。
  2. 誤解の招き: 複雑な概念や操作を「単純」と表現することで、その本質的な複雑さを過小評価させ、誤解を招く可能性があります。
  3. 不正確な表現: 実際には単純ではないプロセスやコードに対して「simply」を使用することは、情報の正確性を損ないます。

このコミットは、Go言語のドキュメントとコメントの品質を向上させ、より包括的で、読者に配慮した表現にするための取り組みの一環です。特に、Go言語が初心者から経験豊富な開発者まで幅広い層に利用されることを考えると、このような言葉遣いの改善は、コミュニティ全体の学習体験とアクセシビリティに貢献します。

前提知識の解説

技術文書における言葉遣いの重要性

技術文書、特にプログラミング言語の公式ドキュメントやライブラリのコメントは、開発者がその技術を理解し、効果的に使用するための主要な情報源です。そのため、文書の明確性、正確性、そしてトーンは非常に重要です。

  • 明確性: 曖昧さのない、理解しやすい言葉で書かれていること。
  • 正確性: 技術的な情報が事実に基づき、誤りがないこと。
  • トーン: 読者に対してどのような印象を与えるか。専門的でありながら、親しみやすく、威圧的でないトーンが望ましいとされます。

「simply」のような単語は、書き手の意図とは裏腹に、読者に対して「これは簡単だから、もし理解できないならあなたの問題だ」というような、無意識の威圧感を与えてしまうことがあります。これは、特に新しい概念を学んでいる読者や、異なるバックグラウンドを持つ読者にとって、学習の障壁となる可能性があります。

Go言語のドキュメンテーション文化

Go言語のプロジェクトは、その設計思想と同様に、ドキュメンテーションにおいても簡潔さ、明確さ、そして実用性を重視しています。公式ドキュメントや標準ライブラリのコメントは、コードの意図を正確に伝え、開発者がGoのイディオムを理解するのに役立つように書かれています。このような文化の中で、「simply」のような主観的で、かつ誤解を招く可能性のある表現を排除することは、ドキュメンテーションの一貫性と品質を保つ上で重要なステップとなります。

技術的詳細

このコミットは、Go言語の様々なドキュメントファイル（HTMLテンプレート、記事、週報など）と、一部の標準ライブラリのコードコメントから「simply」という単語を削除する、という非常に直接的な変更を行っています。

変更の対象となったファイルは以下の通りです。

  • doc/articles/error_handling.html
  • doc/articles/error_handling.tmpl
  • doc/devel/weekly.html
  • doc/gccgo_install.html
  • src/pkg/crypto/cipher/io.go
  • src/pkg/database/sql/driver/driver.go
  • src/pkg/encoding/gob/decoder.go
  • src/pkg/expvar/expvar.go
  • src/pkg/text/tabwriter/tabwriter.go

これらの変更は、コードの機能的な振る舞いには一切影響を与えません。純粋にドキュメントとコメントの表現を改善するためのものです。例えば、src/pkg/crypto/cipher/io.go のコメントでは、StreamReader や StreamWriter が XORKeyStream を呼び出すことについて、「It simply calls XORKeyStream」から「It calls XORKeyStream」に変更されています。これにより、その操作が「単純」であるという主観的な評価を取り除き、客観的な事実のみを記述しています。

この種の変更は、大規模なオープンソースプロジェクトにおいて、ドキュメンテーションの品質と一貫性を維持するために定期的に行われることがあります。特に、多くのコントリビューターが関わるプロジェクトでは、特定の言葉遣いやスタイルガイドラインを徹底することが、長期的なメンテナンス性と新規参入者の学習曲線に大きく影響します。

コアとなるコードの変更箇所

このコミットは、主にドキュメントファイルとGoの標準ライブラリ内のコメントから「simply」という単語を削除しています。以下にいくつかの代表的な変更箇所を示します。

doc/articles/error_handling.html および doc/articles/error_handling.tmpl

--- a/doc/articles/error_handling.html
+++ b/doc/articles/error_handling.html
@@ -415,7 +415,7 @@ the user is an administrator,
 <li>write a constructor function for <code>appError</code> that stores the
 stack trace for easier debugging, 
 <li>recover from panics inside the <code>appHandler</code>, logging the error
-to the console as "Critical," while simply telling the user "a serious error
+to the console as "Critical," while telling the user "a serious error
 has occurred." This is a nice touch to avoid exposing the user to inscrutable
 error messages caused by programming errors.
 See the <a href="defer_panic_recover.html">Defer, Panic, and Recover</a>

src/pkg/crypto/cipher/io.go

--- a/src/pkg/crypto/cipher/io.go
+++ b/src/pkg/crypto/cipher/io.go
@@ -9,7 +9,7 @@ import "io"
 // The Stream* objects are so simple that all their members are public. Users
 // can create them themselves.
 
-// StreamReader wraps a Stream into an io.Reader. It simply calls XORKeyStream
+// StreamReader wraps a Stream into an io.Reader. It calls XORKeyStream
 // to process each slice of data which passes through.
 type StreamReader struct {
 	S Stream
@@ -22,7 +22,7 @@ func (r StreamReader) Read(dst []byte) (n int, err error) {
 	return
 }
 
-// StreamWriter wraps a Stream into an io.Writer. It simply calls XORKeyStream
+// StreamWriter wraps a Stream into an io.Writer. It calls XORKeyStream
 // to process each slice of data which passes through. If any Write call
 // returns short then the StreamWriter is out of sync and must be discarded.
 type StreamWriter struct {

src/pkg/database/sql/driver/driver.go

--- a/src/pkg/database/sql/driver/driver.go
+++ b/src/pkg/database/sql/driver/driver.go
@@ -5,7 +5,7 @@
 // Package driver defines interfaces to be implemented by database
 // drivers as used by package sql.
 //
-// Code simply using databases should use package sql.
+// Most code should use package sql.
 //
 // Drivers only need to be aware of a subset of Go's types.  The sql package
 // will convert all types into one of the following:

コアとなるコードの解説

上記の変更箇所は、いずれも「simply」という単語を削除するか、より客観的な表現に置き換えることで、ドキュメントやコメントのトーンを改善しています。

  • doc/articles/error_handling.html および doc/articles/error_handling.tmpl: エラーハンドリングに関する記事で、「simply telling the user」という表現から「telling the user」に変更されています。これは、ユーザーにエラーメッセージを伝えるという行為が、必ずしも「単純」ではないことを示唆しています。特に、ユーザー体験を考慮したエラーメッセージの設計は、複雑なプロセスである場合があります。

  • src/pkg/crypto/cipher/io.go: StreamReader と StreamWriter のコメントで、「It simply calls XORKeyStream」という記述が「It calls XORKeyStream」に変更されています。これは、これらの構造体が XORKeyStream を呼び出すという事実を述べるだけで、その操作の「単純さ」については言及しないようにしています。暗号化ストリームの処理は、概念的には単純に見えても、その背後にある暗号理論や実装の詳細は複雑であるため、このような変更は適切です。

  • src/pkg/database/sql/driver/driver.go: データベースドライバに関するコメントで、「Code simply using databases should use package sql.」が「Most code should use package sql.」に変更されています。これは、データベースを使用するコードの全てが「単純」であるわけではないことを認識し、より一般的なケースを指す「Most code」という表現に修正しています。データベース操作は、トランザクション管理、エラーハンドリング、パフォーマンス最適化など、多くの複雑な側面を持つため、この変更はより正確な表現と言えます。

これらの変更は、Go言語のドキュメンテーションが、読者に対してより正確で、威圧的でなく、かつ包括的な情報を提供しようとする姿勢を示しています。

関連リンク

参考にした情報源リンク

  • Google Developers Blog: Writing for Developers (Googleの技術文書スタイルガイドの一部で、トーンに関するアドバイスが含まれている可能性があります。特に「Avoid condescending language」のような項目が関連します。)
  • The Go Programming Language Specification (Go言語の公式仕様。ドキュメンテーションのスタイルに関する直接的な言及はないが、Goの設計思想がドキュメンテーションにも反映されていることを理解する上で参考になります。)
  • Effective Go (Go言語のイディオムとベストプラクティスに関する公式ガイド。コードの書き方だけでなく、コメントの書き方にも示唆を与える可能性があります。)
  • Technical Writing Style Guide (一般的な技術文書のスタイルガイド。特定の単語の使用を避けるべき理由について、より広範な視点を提供します。)
  • Why "Simply" Is Not So Simple (PlainLanguage.govのようなサイトは、明確で簡潔なコミュニケーションの重要性を強調しており、「simply」のような単語がなぜ問題となりうるかについて解説している場合があります。)