Qiita などの技術系の記事を読んでて「あ,ココちょっと残念」と思うポイントを書いてみます。自らの反省も込めて。
日本語表現・表記
「値を返却する」という表現
関数やメソッドが値を return することを日本語で「返却する」と表現した記事がたくさんありますが,ものすごい違和感を覚えます。
「値を返す」と書くべきでしょう。
この件は以前書きましたので理由はそちらを見てください。
「値を返却する」って言うな
「可変する」という言葉
「可変する」というおかしな言葉もよく目にします。
「可変」というのは,読んで字のごとく「変わりうる」とか「変えうる」という意味です。英語でいうと variable(vary しうる)ですね。
「PNG の圧縮方式は可逆だ(逆変換が可能だ)」というときの「可逆」と同様の成り立ちなわけです。
可変長配列と言えば,固定長ではなくて,あとから伸ばしたりできるような配列のことですね。
引数が可変とは,メソッドなり関数なりに与える引数の個数が固定ではない(foo(3, 2)
とか foo(4)
とかできる)ということですね。
しかし,「長さが可変だ」とは言えても,「長さを可変する」とは言えません。「長さを変える」と書くべきでしょう。
「ウインドウ幅が可変すると」は「ウインドウ幅が変化すると」と書くべきだし,「ウインドウ幅を可変すると」は「ウインドウ幅を変化させると」と書くべきです。
書籍でも
多くのウェブページと違って,書籍はプロの編集者・校正者の目を通ってから公になります。また,間違えたら直せばいいやのウェブと違い,印刷後に低コストで修正できない書籍では校正時の緊張感が違います。
そのぶん,テキストの品質にはいくぶん期待したいところですが,たまたま今読んでいるレスポンシブウェブデザインの本に
レイアウト幅が可変する段組レイアウト
という表現が出てきて悲しくなりました。「レイアウト幅が可変の段組レイアウト」と書くべきでしょう。
こういう表現を本を読んだ読者の一部は,自身も自然に使ってしまうでしょう。おかしな日本語が再生産されていくわけです。
オマケ(蛇足)
話がそれますが,「可変」で思い出したことを。昔のことなので記憶違いがあるかもしれません。
学生の頃,超有名なプログラミング言語本の第二版の邦訳が出たのをキャンパスの書店で見つけました。私はその言語を名前しか知りませんでしたが,少し背伸びする気分でパラパラめくってみました。
そこには「可変が」とか「可変は」という表現がたくさんありました。「可変」て何だろう? さすがに最先端の言語には,私の知らない概念が出てくるものだな,と感心しました。
後になって,あれはどうも variable(変数)を「可変」と誤訳したんではないかと思いました。それにしても,訳者は variable が変数だと分からずに,どうやって中身を理解したんでしょうか。監訳者は超有名な先生ですが,翻訳原稿を 1 ページもご覧にならなかったのかしらん?
大学院生の頃,同じ科の先生から,訳したい数学の本があるので翻訳に参加しないか,と誘われました。とても翻訳なんて(たとえ下訳でも)できる英語力はありませんでしたので,もちろん断りましたよ。
でも,クズ訳本がどうしてできるのか,そのとき理解しました。
「適用する」を「適応する」
「このやり方を適応する」というような表現をしばしば目にしますが,書きたかったのは「当てはめて用いる」という意味の「適用する」でしょうね。
「適応する」だと,「状況にかなう,当てはまる」とか「適するように変化する」というような意味になります。「この薬が適応する症状」「環境に適応する」というような使い方です。
最初はミスタイプかと思いましたが,どうも混同している人が少なくないようです。
「ポイントを抑える」という表記
「これだけは抑えておきたい」「ポイントを抑える」という表現を非常によく見ますが,この場合の「おさえる」は「しっかりと捉える・理解する・把握する」という意味なので「押さえる」という漢字を使うのがいいでしょう。
「抑える」だと抑止・抑圧の意味になります。「ファイルサイズを抑える」「発熱を抑える」「メモリーリークを抑える」というときに使う漢字です。
なので「テーブル設計の基本知識を抑えよう」と書いてあると,「『基本知識を得よう』と言ってるのか『基本知識をためないようにしよう』と言っているのか,どっちやねん!」とツッコみそうになります。
あまりに多いので,変換ミスというよりも使い分けをご存じないのかなと思います。
※「押さえる」も「抑える」も語源はもちろん同じで,意味の分化に対応して漢字を書き分けているだけではありますが。
「例外を補足する」
「例外(exception)を補足する」という表記もよく目にします。
「補足する」だと「補う」という意味になっちゃいます。例外を捉えるのだから「捕捉する」と書かなければなりません。
文章には適さない口語表現の安易な文字化
ある記事を読んでいて
基本画像は消さない
とありました。「基本画像」って何だろう? 読み返しましたが特に説明はありませんでした。
ちょっと考えて,「基本的に画像は消さない」という意味かな?と思いあたりました。
口語では確かに「基本俺欲しい本は買っちゃうタイプなんすよ」とか「基本 Qiita に質問目的の記事は書かない」なんて言いますけど。
せめて読点を入れて
基本、画像は消さない
とすればよかったと思います。が,そもそもこのような表現は文章にはなじみませんね。
現代の日本語は言文一致とは言うけれど,たいがいの文章は本当にしゃべるようには書きません。それに対して,メールなどの私的な文章やケータイ小説などでは,本当にしゃべるように書くことが広く行われています。こういう文体を新言文一致体と呼ぶこともあります。べつに悪い文体というわけではありませんが,場面によってはふさわしくないこともありますね(かく言う私自身,Qiita でよく使ってますが)
* *
による強調
Qiita など使用されている Markdown 記法に,* *
で囲むと強調されるというのものがあります。
これは em
要素になりますが,スタイルが font-style: italic
です。したがって,日本語では斜体になります。
こんなふうにね。
英語ではローマン体のテキストの中で強調部分にイタリック体を使いますが,日本語で強調部分に斜体など使いません。ふつうは太字にします。印刷物の場合,本文が明朝体のときに,強調部分を太めのゴシック体にするのが一般的です。
英文と和文で,語句を強調するやり方が根本的に違うんです。
よって,* *
を使うべきではありません。アスタリスクが一つ多い ** **
を使うべきでしょう(これは strong
要素になります)。
こんなふうにね
(2016-01-12 追記)コメントで,(HTML5 における)em
と strong
は用途が異なるという主旨のご指摘を戴きました。これに従えば,em
は Qiita では使用を諦め,strong
がふさわしい箇所に ** **
を使いましょう,ということになりますね。
略語
略語は便利なものですが,出てくる文脈によっては意味が取りづらいことがあります。
とりわけ AR,DL,PJ のような英語の頭字語はいくとおりにも解釈できますし,十分に定着した頭字語でなく,その場で臨時に略されたりするとワケが分かりません。
ダウンロードを D/L,ハードウエアを H/W と略す習慣もあります。
このような略語が一目で了解されるためには文脈が重要です。
文脈について二つの問題があると思います。
一つは文脈が書き手の頭の中にあって,文章に十分表現されていないことが多いこと。書き手には「この文脈だから分るだろう」と思えても,その文脈が読み手に伝わっていないことがしばしばあります。
もう一つは文脈さえあれば必ず直ちに分かるというわけではないことです。「AR」は,Ruby on Rails に関する記事なら ActiveRecord で,ユーザーインターフェースなら Augmented Reality なのは自明でしょうか。
略語は,うまく使えば表現が簡潔になり,むしろ読みやすくなったりもします。使ってはいけないものではありません。その用語がその記事におけるキー概念であり,何度も出てくるのであれば,積極的に略語を使ってよいと思います。ただし,よほど自明な略語でない限り,初出時に
ITS(Issue Tracking System)
とか
プロジェクトマネージャー(以下 PM)
などと書く必要があるでしょう。
(2020-01-04 追記)説明なき略語使用の背景には「自分のような初心者が知っているんだから他の人は当然分かるだろう」という思い込みもあるのかも知れません。でもその略語を知らない(あるいは元の語がすぐに出てこない)初心者はたくさんいます。それに,むしろいろいろ知っていると却って惑うことがあります。私もある記事を読んでいて「ML」が機械学習だとすぐには分からず,一瞬 古のプログラミング言語 かと思ったことがありました。
タイトルで中身が十分に分からない
たとえば,Ruby の浮動小数点数の扱いについて「ハッ」と思ったことを書き留めた記事を「Rubyメモ」というタイトルで公開したらどうでしょう? タイトルが表すテーマが内容に比して広過ぎますね。
読者から見たとき,たくさん記事がある中で,自分が読むべきかどうか判断できるタイトルが付いているといいですね。
主題である固有名の説明が無い
たとえば,タイトルが「Kleovitr を単独で動かす」となっていて,本文が
Kleovitr は GlipsFy に組み込んで使うのが普通だけど,単独で使おうとしたらハマったのでメモ。
セットアップのときにパラメーター allow_receiver を OFF にしておくのがポイント。それに
のように始まっていたらどうでしょうか。
Kleovitr(ライブラリー? フレームワーク? アプリ? それとも?)が何なのか分らなくてイライラします。ちなみにこれは今考えた架空の固有名です。
「Kleovitr を知らない人は記事読まないからいいんじゃないの?」と思う人もいるかもしれませんが,そんなことはありません。
この記事に例えば「Ruby」ってタグが付いてたら,「Ruby」をフォローしてる人の何割かはとりあえず見るでしょう。Kleovitr は,今は知らないけど,もしかしたら自分にとってとても有用なものかもしれないのです。
記事の冒頭に Kleovitr が何をするものなのか一言でも書いてあれば,「自分には関係ない」とか「面白そう,あとで調べよっと」などと判断できます。
ほぼリンクだけ
タイトルと 1 行くらいの説明があって,あとは外部サイトへのリンクだけ,という記事がありますよね。
外部の良い記事があったから紹介したい,下手に自分がいろいろ書くよりもリンク先を見てもらったほうがいい,と思ったのかもしれません。
でもやっぱり,リンク先を読むべきかどうか判断できるような説明がついていると親切だと思います。リンク先がそのテーマの何について書かれているのか,どういう読者に勧められるのか,投稿者はそれをどう評価しているのか,とか。
ほぼコードだけ
タイトルと(ほぼ)コードだけの記事も見かけます。
書いた人は「コードを見てくれれば分かる」というつもりかもしれませんが,やはりそのコードを提示する理由などを書いてほしいと思います。こうすればうまくいった,とか。
処理系が書いてない
とりわけ正規表現について。
タグに「正規表現」が付いているものの,処理系についての注記のない記事を多く見かけます。
正規表現は処理系による違いが大きいので,処理系は必ず書かなければいけません。
たとえば \d
は,Ruby では(1.8 も 2.2 も)[0-9]
と等価ですが,処理系によっては非 ASCII の数字,つまり全角数字とかアラビア文字の数字(١٢٣٤)を含んだりします。
\r
と \n
の意味もまちまちです。
戻り読み (?<= )
が使えない処理系もあります。
文字列 foo
に対し,x?
で検索して -
に置換すれば -f-o-o-
となるはずですが,ならない処理系もあります。
正規表現エンジンである鬼車および鬼雲は,標準では文字コード指定を \x{2065}
と書きますが,Ruby の鬼車・鬼雲は \u{2065}
と書きます。
Ruby や Perl では foo\n
というテキストの末尾に ^
がマッチしませんが,マッチする処理系も少なくありません。
タイポ(入力ミス)
「内臓メモリー」「不動少数点数」のような変換ミス,「reciever」「databace」のような綴りの間違い,「ファイルにを保存する」のような推敲時の修正ミスなどがあると,やはり読みづらいものです。
この手の入力ミスをこの業界では「タイポ」というそうですね。
この言葉はもともと英語の印刷用語 typo [táɪpoʊ]で,typographic typographical error(文字組版上の誤り,つまり誤植)のことです。どういう経緯でプログラマーたちが使うようになったのか分かりませんが,日本の印刷業界で知ってる人はあまり多くないと思います。
それから,読みやすさに大きくは影響しないものの,「FireFox」,「Javascript」「100 KWh」(それぞれ正しくは Firefox,JavaScript,100 kWh)のような大文字/小文字の間違いも無くしたいですね。もっとも「EPUB」のように 公式ロゴ で「ePUB」の表記が使われてて,何が正しいのか迷うものもあるにはありますが。
「一つづつ」のような歴史的仮名遣いの混在も,避けたほうがよいと思います(現代仮名遣いは「一つずつ」)。
(2016-01-12 追記)現代仮名遣いで「づつ」は〈許容〉でした。追記 参照
タイポを防ぐには昔から言われている次のようなことが効果的です。
- **書いて少し経ってから見直す。**時間を置くと脳の中に一時的に用意された材料(これがタイポの原因になったりもする)がボッソリ落ちて,いくぶん他人の目で見ることができる。
- **スペルチェッカーを使う。**ブラウザーからの投稿なら組込みのスペルチェッカーが働くので,何もしなくても一般的な英単語のスペルミスはすぐ気づくはず。辞書に無い「Gemfile」「CoffeeScript」「Sass」などの単語は予め登録しておけば邪魔にならない。
- **コピー&ペーストする。**手で打つから間違うので,コピペでいけるものはコピペでやればいい。ただし,コピー元が正しいという確信が必要。コピー範囲を誤らないことも大切。
スペルチェッカーについてもう一言。 Kobito がスペルチェック機能を持っていない ことが Qiita の記事のミススペルを助長していると思います。
同じ内容
たいして変わらない内容の記事が何度も何度も違う書き手によって投稿されます。少しでも新しい点があるとよいのですが。また,既存の良い記事への参照もあるといいですね。
おそらく,過去記事を調べないで投稿してるんだと思います。
これについては(いや他の項についても)私自身,大いに反省しなければなりません。
Qiita に同じような内容の記事が多い遠因というか背景としては,Qiita の検索機能が貧弱ということもあるかもしれません。
また,記事が評価される仕組みがストックしかなく,多くの良記事が埋もれてしまっていることもあると思います。
Markdown のルールで正しく書かれていない
コード例がバッククォート三つで挟まれていない記事をよく見ます。
```
なんとかかんとか
```
のようにバッククォート三つで挟めばコード表示になります。(前後には空行を入れましょう。入れなくても正しく表示してくれる場合もあるし,そうでない場合もあります)
また,
```rb
s = "foo" * 3
```
のように言語を表す文字列を付ければ(この例では「rb」で Ruby を指定)
s = "foo" * 3
のように見やすくハイライト表示してくれるのに,付いていないものがよくあります。
また,文中に $
があるために TeX の数式と解釈されてしまってそこ以降がぐちゃぐちゃになっているものもよく見ます。プレビューでよく確認すれば防げるでしょう。
ハイライト可能な言語とその指定方法は「Qiitaでシンタックスハイライト可能な言語一覧 | Syntax Highlighting: List of Supported Language at Qiita」にあります。
記法全体の説明は「Markdown記法 チートシート」にあります。
追記
2015-12-29
「適用する/適応する」については @magicant さんが既に「適用 vs 適応」を 2014 年に書かれていました。
2016-01-12
Twitter で,「この記事自身,タイトルで中身が分からない」という主旨のご指摘を複数の方からいただきました。ぐうの音も出ません。(が,失敗は失敗として,タイトルを大幅には変えないことにします)
また,「Qiita の記事って書いてあるけど,Qiita に限らない話だよね」という主旨のご指摘も複数の方からいただきました。これについては最初から〈技術文書全般に通じることも含むけど,あくまで Qiita の記事を観察した結果に基づいて書く〉方針でした。技術文書一般について書くならもっと別の例も挙げます。
なのですが,@GeckoTang さんからタイトルの「Qiita の記事」を「Qiita などの技術系の記事」にするよう編集リクエストをいただき,迷った末せっかくなので採用させていただきました(感謝)。
typo のことを「typographic error」と書いていましたが,これ自身がタイポでした。『ランダムハウス』や『リーダーズ』によれば「typographical error」です。
〈「一つづつ」は歴史的仮名遣い。現代仮名遣いなら「一つずつ」〉という主旨のことを書きました。
これは概ね正しいのですが,現代仮名遣いにおいて「づつ」は許容されていることが分かりました。
「現代仮名遣い」(昭和61年内閣告示第1号) に,「ず」が本則だけど「づ」と書いてもよい語の例として「ひとりずつ」が挙がっているのが根拠です。
なお,この内閣告示の旧版にあたる「現代かなづかい」(昭和21年内閣告示第33号)では「づつ」は許容されていなかったらしいのですが,よく調べてません。
2016-01-24
この記事に対する(コメント欄以外での)反応を眺めていて,「しまった」と思いました。
「こういうことがあるから怖くて記事が書けない」「書きにくい」と感じた方がいらっしゃったようです。
この記事の意図は,問題点をあげつらって批判するところにはなく,こういう点に気をつけるともっと良いのでは,ということでした。
だいたい,ここで指摘したことがもしケシカランことなのであれば,この記事自体がケシカラン記事です(自分が指摘した問題が少なくとも三つあった)。
結果的にいくらかの方を萎縮させてしまったようですみません。
@onomame さんがコメント欄に
あまり校閲に時間を掛けるより、より1本でも多くの記事を書いて欲しいと思うのです。
と書かれていることに基本的に賛成です。
(まあ「校閲」は,ふつうは他人が書いたものについて使う言葉だと思いますが)