6. 短い文
通常ソフトウェアエンジニアは実装するコードの行数を最小化しようとします。その理由は次の通りです:
-
一般的に短いコードは長いコードより読みやすい。
-
一般的に短いコードは長いコードより保守しやすい。
-
コードが一行増えるごとに間違いが起こり得る場所が増える。
実は、テクニカルライティングでも同じ規則が成り立ちます:
-
短いドキュメントは長いドキュメントより速く読める。
-
一般的に短いドキュメントは長いドキュメントより保守しやすい。
-
ドキュメントが一行増えるごとに間違いが起こり得る場所が増える。
最も短いドキュメントの実装を見つける作業には時間がかかりますが、長い目で見れば行う価値があります。短い文を使えば長い文よりも効果的に読者へ語りかけることができ、さらに短い文は簡単に理解できます。
一つの文では一つのことだけを述べる
一つの文では一つの意見・議論・概念に集中してください。プログラムの一つの文が一つのタスクを実行するように、一つの文は一つのことを読者に伝えるべきです。例えば、次の非常に長い文は複数の事実を述べています:
The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy invented Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way.
(1950 年代後半は、IBM が Fortran を 1957 年にリリースし、翌年ジョン・マッカーシーが Lisp を発明し、これによりプログラマーが手続き的および再帰的な問題解決法の両方を手にしたので、プログラミング言語にとって重要な年代だった。)
この長い文を一つのことだけを述べる文の並びへと分解すれば、次の文章となります:
The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively.
(1950 年はプログラミング言語にとって重要な年代だった。IBM は Fortran を 1957 年にリリースした。その翌年ジョン・マッカーシーは Lisp を発明した。このため 1950 年代の終わりには、プログラマーは手続き的もしくは再帰的に問題を解くことができた。)
練習問題
次の長すぎる文を、複数の短い文に書き換えてください。修正を徹底的に行う必要はなく、一つの文をいくつかの文に分ければ十分です。
In bash, use the if
, then
, and fi
statements to implement a simple conditional branching block in which the if
statement evaluates an expression, the then
statement introduces a block of statements to run when the if
expression is true, and the fi
statement marks the end of the conditional branching block.
(bash で単一条件分岐ブロックを実装するには if
, then
, fi
文が利用でき、if
文は式を評価し、then
文は if
の式が真のときに実行される文ブロックを始め、fi
文は条件分岐ブロックの終端を表す。)
In bash, use an if
, then
, and fi
statement to implement a simple conditional branching block. The if
statement evaluates an expression. The then
statement introduces a block of statements to run when the if
expression is true. The fi
statement marks the end of the conditional branching block.
(bash で単一条件分岐ブロックを実装するには if
, then
, fi
文を利用できる。if
文は式を評価する。then
文は if
の式が真のときに実行される文ブロックを始める。fi
文は条件分岐ブロックの終端を表す。)
(出来上がる文が明快だとは言えませんが、元の文よりはずっと読みやすくなっています。)
長い文をリストにする
技術文書に含まれる長い文をよく見ると、文から飛び出したがっているリストが見つかることがよくあります。例として次の文を考えます:
To alter the usual flow of a loop, you may use either a break
statement (which hops you out of the current loop) or a continue
statement (which skips past the remainder of the current iteration of the current loop).
(通常のループの流れを変えるには、break
文 (現在のループから脱出する) または continue
(現在のループの現在の反復の残りを飛ばす) のいずれかが利用できる。)
長い文の中に接続詞 or (または) を見つけたら、その文を箇条書きにできないかを考えてください。また長い文の中に項目やタスクのリストが埋め込まれているなら、箇条書きや番号付きリストへのリファクタリングを考えてください。例えば上の例文には接続詞 or が含まれるので、この文は次のように箇条書きを使って書き換えられます:
To alter the usual flow of a loop, call one of the following statements:
break
, which hops you out of the current loop.continue
, which skips past the remainder of the current iteration of the current loop.
(通常のループの流れを変えるには、次の文のいずれかを呼ぶ:
break
: 現在のループから脱出するcontinue
: 現在のループの現在の反復の残りを飛ばす)
練習問題
次の文をリファクタリングしてより短く明確にしてください。答えの文にはリストを含めてください:
-
To get started with the Frambus app, you must first find the app at a suitable store, pay for it using a valid credit or debit card, download it, configure it by assigning a value for the Foo variable in the /etc/Frambus file, and then run it by saying the magic word twice.
(Frambus アプリを開始するには、まずアプリを適切なストアで見つけ、有効なクレジットカードまたはデビットカードでアプリを購入し、アプリをダウンロードし、ファイル
/etc/Frambus
にあるFoo
変数に値を設定してアプリを設定し、魔法の言葉を二回唱えてアプリを実行する。) -
KornShell was invented by David Korn in 1983, then a computer scientist at Bell Labs, as a superset of features, enhancements, and improvements over the Bourne Shell (which it was backwards compatible with), which was invented by Stephen Bourne in 1977 who was also a computer scientist at Bell Labs.
(KornShell は 1983 年に当時ベル研の計算機科学者だったデビッド・コーンによって、1977 年にこちらもベル研の計算機科学者だったスティーブン・ボーンによって開発された (KornShell が互換性を持っていた) Bourne Shell に対する機能拡張や修正・改善として開発された。)
-
Take the following steps to get started with the Frambus app:
- Find the app at a suitable store.
- Pay for the app using a valid credit or debit card.
- Download the app.
- Configure the app by assigning a value for the Foo variable in the /etc/Frambus file.
- Run the app by saying the magic word twice.
(Frambus アプリを開始するには、次のステップを実行すること:
- 適切なストアで Frambus アプリを見つける。
- 有効なクレジットカードまたはデビットカードでアプリを購入する。
- アプリをダウンロードする。
- ファイル /etc/Frambus にある Foo 変数に値を設定してアプリを設定する。
- 魔法の言葉を二回唱えてアプリを実行する。)
-
The following two Bell Labs computer scientists invented popular shells:
- Stephen Bourne invented the Bourne Shell in 1977.
- David Korn invented the KornShell in 1983.
The KornShell's features are a backwards-compatible superset of the Bourne Shell's.
(次に示す二人のベル研の計算機科学者は有名なシェルを開発した:
- スティーブン・ボーンは 1977 年に Bourne Shell を開発した。
- デビッド・コーンは KornShell を 1983 年に開発した。
KornShell の機能は Bourne Shell の機能を互換性を保ったまま拡張したものである。 )
余計な単語を削除する
多くの文には埋め草 ──読者の役に立つことなく無駄に空間を占有するジャンクフードのような単語── が含まれています。例えば、次の文に含まれる不必要な単語を見つけてみてください:
An input value greater than 100 causes the triggering of logging.
(100 より大きい入力値はログの起動を引き起こす。)
couses the triggering of (...の起動を引き起こす) をずっと短い動詞 triggers に置き換えれば、文が短くなります:
An input value greater than 100 triggers logging.
(100 より大きい入力値はログを起動する。)
経験を積んでいけば、余計な単語を見つけたときに言葉にならない喜びを感じるようになるでしょう。例えば、次の文ではどうでしょうか:
This design document provides a detailed description of Project Frambus.
(このデザインドキュメントは Project Frambus の詳細な説明を提供する。)
provides a detailed description (詳細な説明を提供する) という言い回しは details (詳述する) という一つの動詞に短縮でき、次の文が得られます:
This design document details Project Frambus.
(このデザインドキュメントは Project Frambus について詳述する。)
よく目にする長い言い回しとその短い言い換えを次の表に示します:
長い | 短い |
---|---|
at this point in time (この時点において) |
now (現在) |
determine the location of (...の位置を特定する) |
find (...を見つける) |
is able to (...することができる) |
can (...できる) |
練習問題
次の文を意味を変えることなく短くしてください:
-
In spite of the fact that Arnold writes buggy code, he writes error-free documentation.
(アーノルドはバグの多いコードを書くという事実にもかかわらず、彼はエラーのないドキュメントを書く。)
-
Changing the sentence from passive voice to active voice enhances the clarification of the key points.
(文を受動態から能動態に変更すると、重要な点の明確さが際立つ。)
-
Determine whether Rikona is able to write code in COBOL.
(リコナが COBOL のコードを書くことができるかどうかを調べる。)
-
Frambus causes the production of bugs, which will be chronicled in logs by the LogGenerator method.
(Frambus はバグの生成を引き起こし、それは LogGenerator メソッドによってログとして保存される。)
解答例を示します:
-
Although Arnold writes buggy code, he writes error-free documentation.
(アーノルドはバグの多いコードを書くが、エラーのないドキュメントを書く。)
別の解答例: Arnold writes buggy code. However, he writes error-free documentation.
(アーノルドはバグの多いコードを書く。しかし、彼はエラーのないドキュメントを書く。)
-
Changing the sentence from passive voice to active voice clarifies the key points.
(文を受動態から能動態にすると重要な点が明確になる。)
-
Determine whether Rikona can code in COBOL.
(リコナが COBOL のコードを書けるか調べる。)
-
Frambus produces bugs, which the LogGenerator method logs.
(Frambus がバグを生成し、それを LogGenerator メソッドが記録する。)
従属節を避ける (スキップ可)
主語と述語を含む、文の独立した断片を節 (clause) と呼びます。全ての文は次の要素からなります:
- 主節 (main clause)
- ゼロ個以上の従属節 (subordinate clause)
従属節は主節の文意を修飾します。名前が示す通り、従属節は主節よりも重要性が劣ります。次に示すのは従属節を持つ文の例です:
Python is an interpreted programming language, which was invented in 1991.
(Python はインタープリタによって実行されるプログラミング言語であり、1991 年に開発された。)
- 主節: Python is an interpreted programming language
- 従属節: which was invented in 1991
従属節はたいてい先行する単語によって特定できます。従属節の先頭に付く単語の (ごく) 一部を次のリストに示します:
- which
- that
- because
- until
- unless
- since
従属節の前にはコンマが付くこともあれば付かないこともあります。例えば次の文に含まれる従属節 (ハイライトされた部分) は because という単語で始まりますが、コンマはありません:
I prefer to code in C++ because I like strong data typing.
(私は強いデータ型付けが好きなので、C++ でコードを書くのが好きだ。)
推敲では「一つの文では一つのことを述べる」というルールを念頭において、従属節に注目してください。その従属節は主節の文意を拡張していますか、それとも別のことを述べていますか? もし後者なら、従属節を個別の文に分けられないかを考えてください。
練習問題
主節とは異なることを述べている従属節を持つ文がどれかを答えてください。書き換える必要がある文を指摘できれば、文を書き換えなくて構いません。
-
Python is an interpreted language, which means that the language can execute source code directly.
(Python はインタープリタ言語であり、これはこの言語がソースコードを直接実行できることを意味する。)
-
Bash is a modern shell scripting language that takes many of its features from KornShell 88, which was developed at Bell Labs.
(Bash は KornShell 88 からたくさんの機能を受け継いだ現代的なシェルスクリプト言語であり、ベル研で開発された。)
-
Lisp is a programming language that relies on Polish prefix notation, which is one of the systems invented by the Polish logician Jan Łukasiewicz.
(Lisp はポーランド前置記法を使ったプログラミング言語であり、ポーランド前置記法はポーランド人論理学者ヤン・ウカシェヴィチよって開発された体系の一つである。)
-
I don't want to say that Fortran is old, but only radiocarbon dating can determine its true age.
(Fortran が古いと言いたいわけではないが、本当の年齢を測定できるのは放射性炭素年代測定だけだ。)
従属節に色を付けて示します:
-
Python is an interpreted language, which means that the language can execute source code directly.
この従属節は主節の文意を拡張するものなので、このままで構いません。
-
Bash is a modern shell scripting language that takes many of its features from KornShell 88, which was developed at Bell Labs.
一つ目の従属節は主節の文意を拡張するものですが、二つ目の従属節は別の話をしています。二つ目の従属節は別の文とするべきです。
-
Lisp is a programming language that relies on Polish prefix notation, which is one of the systems invented by the Polish logician Jan Łukasiewicz.
一つ目の従属節は主節の文意を拡張するものですが、二つ目の従属節は別の話をしています。二つ目の従属節は別の文とするべきです。
-
I don't want to say that Fortran is old, but only radiocarbon dating can determine its true age.
この従属節は主節の文意を拡張するものなので、このままで構いません。
that と which の使い分け
that と which はどちらも従属節を始める単語として使えます。何が違うのでしょうか? 実を言えば、いくつかの国では、この二つの単語をほとんどの場合で交換できます。しかし that と which を適当に使えば間違いなく、文法にうるさいアメリカ人の読者が怒って「あなたもまた that と which を一緒くたにして!」と言ってくることでしょう。
アメリカ人が読む可能性のある文書を書くときは、which は重要でない従属節に使い、that はそれ無しには文が成り立たない重要な従属節に使ってください。例えば次の文の重要なメッセージは Python がインタープリタ言語であることであり、"Guido van Rossum invented" の部分は無くても文が成り立ちます:
Python is an interpreted language, which Guido van Rossum invented.
(Python はインタープリタ言語であり、グイド・ヴァン・ロッサムによって発明された。)
一方で、次の文には "don't involve linear algebra" が欠かせません:
Fortran is perfect for mathematical calculations that don't involve linear algebra.
(Fortran は線形代数が関係しない数学計算に最適だ。)
文を声に出して読んだときに従属節の直前に間があるなら、そこでは which を使ってください。間がないなら that を使ってください。上の二つの例文を声に出して読んでみましょう。一つ目の文には間があるのに気が付きましたか?
which の前にはコンマを置き、that の前にはコンマを置かないでください。