CodeZine(コードジン)

特集ページ一覧

「オリジナルを探せ!」~ソフトウェア開発者に贈るテクニカルライティングの極意

テクニカルライティング作法・外伝 第5回

  • LINEで送る
  • このエントリーをはてなブックマークに追加
2019/04/17 11:00

目次

テクニカルライティングの正確さを担保するためオリジナルに当たる

 以上のように情報を探して答えが見つかれば、それがプログラミングのためだったら、後はコーディングしてみてちゃんと動けばOKでしょう。ですが、テクニカルライティングではもう少し突っ込んで調べます。

 というのも、とりあえず見つけた答だけでは不十分な可能性があるからです。次のような可能性が考えられます。

  • 間違っている可能性:ブログ記事などでは、説明が間違っていたり、情報が古くなっていることがあります
  • 補足情報が必要な可能性:テクニカルライティングとしては説明しておくべき補足情報、例えば前提条件や制限事項といったことがブログ記事などでは省略されていることがあります

 例として、Visual Basic(VB)の不思議な挙動を調べてみましょう。

Visual Basicでは値型にnullを代入できる!?

 VBにはNothingというキーワードがあります。「JavaやC#のnullと同じだよ」と、とりあえず説明されることが多いです。そう思って使っている分には、たしかにnullと同じように思えます。ところが、次に示すようなコードに出くわすことがあります。他人が書いたものだったり、自分でうっかり間違えて書いてしまったりで。

VBで値型にNothingを代入するコード例
VBでは値型にもNothingを代入できる(Visual Studio 2019 RC)

 なんと値型の変数にNothingが代入できてしまいます。値型変数をNothingとも比較できます。これはいったい何でしょう? 調べてみたらブログ記事のネタにできそうですね。

nullポインタの0番地がキャストされて入る?

 ググっていくと、「値型の変数にNothingは代入できない」と書いている記事も見つかります。そんなはずはないですね。実際に代入できてしまっているんですから。

 「Nothingを代入するとメモリーが0で埋められる」というような記事も見つかります。あ、それっぽいですね。C/C++をやっている人だと、「そうか、gccとかだとNULLポインタを整数に代入できるもんな。0番地を整数に突っ込むんで警告は出るけど」と納得しちゃうでしょうか。

 具体的なURLを示すのは申し訳ない気がするので控えますが、上のように間違っていたり誤解を招く説明をしていたりするWebページが存在します。そのような説明をうっかり鵜呑みにしてしまわないためには、どうすればよいでしょうか?

オリジナルを探す

 それにはオリジナル(原典)を確認することです。開発元による説明ですね。それが最も信頼性の高い情報でしょう。

 そこで、ググるときのキーワードに、開発元のサイトやそのサイトの名称などを追加します。上の例なら、「vb nothing msdn」や「vb nothing site:docs.microsoft.com」などとします(「msdn」はMicrosoftの開発者向けドキュメントの旧サイト)。

 オリジナルに当たるとき、もう1つ気を付けてほしいことがあります。できるだけ、原語のページを見てください。日本語訳のページは、翻訳が間違っていることもあるからです。あるいは、まともに読めない機械翻訳のこともあります。

 次の2つの画像は、VBのNothingを解説しているMicrosoftのページの一部です。日本語訳の「Nothing Visual Basic では異なりますnullでC#します」などは、ちょっと意味不明だと思います。原文(英語)の方は、翻訳ソフトと辞書の助けを借りて読んでいけばちゃんと理解できるでしょう。そこまでに調べてきた知識を確認するだけですから、かなり英語が苦手な人でもなんとかなります。

Nothingの解説ページ(日本語)
Nothingの解説ページ(日本語)
Nothingの解説ページ(英語)
Nothingの解説ページ(英語)

 そのサイトで日本語と英語を切り替える方法を見つけておきましょう。Microsoftの場合は、URLの「ja-jp」を「en-us」に直すのが早いです。

 ちなみに、今回取り上げたVBのNothingの挙動の理由は、日本語訳の冒頭にあるように「任意のデータ型の既定値」だからです。なのでクラスではnullになり、値型では0をセットしたオブジェクトになるのです。C#でこれに該当するのは、nullというよりもdefault(T)式です。Javaでいうと、GuavaDefaults.defaultValue(T)メソッドを使うようなものです。なお、VBでは値型の既定値が0なので、「Nothingを代入するとメモリーが0で埋められる」という説明と、結果としては同じことになります。

まとめ

 情報を検索するときに、プログラミング言語やプラットフォームもキーワードに追加すると見つけやすいです。また、ある程度分かってきたら利用するクラスやメソッド名などで改めて検索してみると、より深い知見が得られることもよくあります。

 テクニカルライティングでは結果として答が合っているだけでは不十分です。正確な説明や前提条件などを知るために、最後は開発元のオリジナル(原典)の解説も確認しましょう。

関連リンク



  • LINEで送る
  • このエントリーをはてなブックマークに追加

バックナンバー

連載:テクニカルライティング作法・外伝

もっと読む

著者プロフィール

  • biac(ばいあっく)

    HONDA R&Dで自動車の設計をやっていた機械屋さんが、技術の進化スピードに魅かれてプログラマーに。以来30年ほど、より良いコードをどうやったら作れるか、模索の人生。わんくま同盟の勉強会(名古屋)で、よく喋ってたりする。 2014/10~2019/6 Microsoft MVP (Windo...

あなたにオススメ

All contents copyright © 2005-2021 Shoeisha Co., Ltd. All rights reserved. ver.1.5