Effective Go 翻訳 ~ Commentary

Effective Go 翻訳 – Commentary

Go provides C-style /* */ block comments and C++-style // line comments. Line comments are the norm; block comments appear mostly as package comments, but are useful within an expression or to disable large swaths of code.

https://golang.org/doc/effective_go#commentary

GoはC言語スタイルの/* */ ブロックコメントとC++スタイルの//行コメントを提供します。行コメントは標準です。ブロックコメントは大部分はパッケージコメントとして現れますが、式内や、またはコードの広範囲を無効にする場合に有効です。

The program—and web server—godoc processes Go source files to extract documentation about the contents of the package. Comments that appear before top-level declarations, with no intervening newlines, are extracted along with the declaration to serve as explanatory text for the item. The nature and style of these comments determines the quality of the documentation godoc produces.

https://golang.org/doc/effective_go#commentary

プログラム（およびウェブサーバ）のgodocはGoのソースファイルを処理し、パッケージのコンテンツに関するドキュメントを抽出します。トップレベルの宣言の前に表示され、改行が介在しないコメントは宣言と一緒に抽出され、アイテムの説明テキストとして提供されます。これらコメントの性質とスタイルはgodocが生成するドキュメントの品質を決定づけます。

Every package should have a package comment, a block comment preceding the package clause. For multi-file packages, the package comment only needs to be present in one file, and any one will do. The package comment should introduce the package and provide information relevant to the package as a whole. It will appear first on the godoc page and should set up the detailed documentation that follows.

https://golang.org/doc/effective_go#commentary

全てのパッケージは、パッケージ節の前に位置するブロックコメントであるパッケージコメントを持つべきです。複数のファイルを持つパッケージでは、パッケージコメントは一つのファイルにのみ表示される必要があり、それはどのファイルでも構いません。パッケージコメントはパッケージを紹介し、パッケージ全体に関する情報を提供するべきです。それはgodocページの最初に表示され、次のように詳細化されたドキュメントを設定するべきです。

/*
Package regexp implements a simple library for regular expressions.

The syntax of the regular expressions accepted is:

    regexp:
        concatenation { '|' concatenation }
    concatenation:
        { closure }
    closure:
        term [ '*' | '+' | '?' ]
    term:
        '^'
        '$'
        '.'
        character
        '[' [ '^' ] character-ranges ']'
        '(' regexp ')'
*/
package regexp

If the package is simple, the package comment can be brief.

https://golang.org/doc/effective_go#commentary

もしパッケージがシンプルであるなら、パッケージコメントは簡潔にできます。

// Package path implements utility routines for
// manipulating slash-separated filename paths.

Comments do not need extra formatting such as banners of stars. The generated output may not even be presented in a fixed-width font, so don’t depend on spacing for alignment—godoc, like gofmt, takes care of that. The comments are uninterpreted plain text, so HTML and other annotations such as _this_ will reproduce verbatim and should not be used. One adjustment godoc does do is to display indented text in a fixed-width font, suitable for program snippets. The package comment for the fmt package uses this to good effect.

Depending on the context, godoc might not even reformat comments, so make sure they look good straight up: use correct spelling, punctuation, and sentence structure, fold long lines, and so on.

Inside a package, any comment immediately preceding a top-level declaration serves as a doc comment for that declaration. Every exported (capitalized) name in a program should have a doc comment.

Doc comments work best as complete sentences, which allow a wide variety of automated presentations. The first sentence should be a one-sentence summary that starts with the name being declared.

https://golang.org/doc/effective_go#commentary

コメントはbanners of stars(？)のような追加フォーマットを必要としません。生成された出力は固定幅フォントで表示されない場合があるため、整列のためのスペースに依存しないでください。gofmtのようにgodocがそれに対処します。コメントは解釈されない平文であるため、HTMLや_this_のようなその他アノテーションは逐語的に再生成され、使用されるべきではありません。godocが行う一つの調整は、プログラムのスニペットに適した、固定幅のフォントでインデントされたテキストを表示することです。fmtパッケージのパッケージコメントはこれを効果的に使用しています。

コンテキストに応じて、godocはコメントを再フォーマットしない場合もあるため、正しいスペリング、句読点、文系、長い行の折り畳みなど、コメントがまっすぐ見えるようにしてください。

パッケージの内部では、最上位の宣言の直前のコメントは、その宣言のdocコメントとして機能します。プログラムの全ての出力された（大文字の）名前はdocコメントを持つべきです。

docコメントは完全な文章としてベストに機能し、それは様々な自動化プレゼンテーションを可能にします。最初の文章は宣言の名前で始まる要約の一文であるべきです。

// Compile parses a regular expression and returns, if successful,
// a Regexp that can be used to match against text.
func Compile(str string) (*Regexp, error) {

If every doc comment begins with the name of the item it describes, you can use the doc subcommand of the go tool and run the output through grep. Imagine you couldn’t remember the name “Compile” but were looking for the parsing function for regular expressions, so you ran the command,

https://golang.org/doc/effective_go#commentary

もし全てのdocコメントが説明する項目の名前から始まるなら、あなたはgoツールのdocサブコマンド使うことができ、grepを通じて出力を実行できます。あなたは”Compile”という名前を思い出せないが、正規表現のパースファンクション探していたと想像してみると、あなたは次のコマンドを実行した。

$ go doc -all regexp | grep -i parse

If all the doc comments in the package began, “This function…”, grep wouldn’t help you remember the name. But because the package starts each doc comment with the name, you’d see something like this, which recalls the word you’re looking for.

https://golang.org/doc/effective_go#commentary

もしパッケージ内の全てのdocコメントが”This function…”で始まるなら、grepはあなたが名前を思い出す手助けをしないだろう。しかし、パッケージはそれぞれのdocコメントを名前から始めるため、あなたは探しているワードを思い出す次のようなものを見ます。

$ go doc -all regexp | grep -i parse
    Compile parses a regular expression and returns, if successful, a Regexp
    MustCompile is like Compile but panics if the expression cannot be parsed.
    parsed. It simplifies safe initialization of global variables holding
$

Go’s declaration syntax allows grouping of declarations. A single doc comment can introduce a group of related constants or variables. Since the whole declaration is presented, such a comment can often be perfunctory.

https://golang.org/doc/effective_go#commentary

Goの宣言シンタックスは宣言のグルーピングを許可します。一つのdocコメントは関連する定数や変数のグループを紹介できます。宣言全体が表示されているので、そのようなコメントはしばしば形式的である可能性があります。

// Error codes returned by failures to parse an expression.
var (
    ErrInternal      = errors.New("regexp: internal error")
    ErrUnmatchedLpar = errors.New("regexp: unmatched '('")
    ErrUnmatchedRpar = errors.New("regexp: unmatched ')'")
    ...
)

Grouping can also indicate relationships between items, such as the fact that a set of variables is protected by a mutex.

https://golang.org/doc/effective_go#commentary

グルーピングは、変数のセットがmutexで保護される事実のように、項目間の関係を示すこともできます。

var (
    countLock   sync.Mutex
    inputCount  uint32
    outputCount uint32
    errorCount  uint32
)

【自分用】文法/熟語メモ

along with + 人（人と一緒に）、along with + 物（物に加えて）

as a whole （全体として、ひとまとめで、概して）

may not ~（[許可]〜してはいけない、[推量]〜でないかもしれない）

depend on ~（〜よって、〜に応じて）

start with ~（〜から始まる、〜から始める）

【自分用】単語メモ

参考

along with の意味
as a whole の使い方
may の使い方
depending on の使い方
start with の使い方