ソフトウェアエンジニアが書いた文章をレビューするときに考えていること

https://gyazo.com/949bac502d07c88e157c00d7442ca0cf

はじめに

エンジニアリング・マネジメント領域のお仕事を担当していると、ソフトウェアエンジニアが書いた文章をレビューする機会があります。それは社内のドキュメントであったり、この文章のように一般公開されるものだったりします。数年に渡って数え切れないほどのレビューを繰り返しているうちに、自分がどういった観点でレビューを行っているのか少しずつわかってきたので、その一部を紹介します。

文脈とスコープを意識する

この記事のタイトルでは「ソフトウェアエンジニア」という書き方を採用しました。ソフトウェア業界の人だけが読むとは限らないからです。このように、文章の置き場所や公開範囲に合わせて表現を選ぶのは重要です。レビューにおいても「これ、社外の人が読んでわかりますかね？」とコメントをすることはよくあります。

社内に閉じたコミュニケーションばかりしていると、文脈やスコープに意識が向きにくくなると思います。種々のコミュニティに参加してさまざまな文脈をもった人々と接することで、読み手にあわせた文章を書く力も向上していくことでしょう。

表現したいことと言葉のズレを小さくする

リモートワークでは、家族と協力したり、仕事用のスペースを確保したりすることが重要だ。

という一文があったとします。ここでの「リモートワーク」は「在宅勤務」への書き換えを検討する余地があります。なぜなら、就業場所として「自宅」を想定した主張をしているからです。リモートワークが間違いというわけではありませんが、主張したい内容によりマッチする言葉を選べば、読者のスムーズな理解の助けになります。

ぼくが見ている範囲でよく陥る罠は「流行り言葉に吸い寄せられる」です。自分の感覚を素直に自分の言葉で語ればいいシーンで流行り言葉を持ち出してしまって、言いたいことの芯がぶれちゃうことってありますよね。自分にもあります。そういった意味で最近のぼくが使用を控えているものとして「技術的負債」「心理的安全性」「リスキリング」などがあります。

モノの名前に意識を向ける

JavaScript というプログラミング言語があります。2022 年 12 月現在、世界中で広く使われている言語です。ソフトウェアエンジニアの求人票にもよく記載されています。ところで、ぼくが採集した表記パターンにはけっこうなバリエーションがあります。

JavaScript

Javascript

javascript

JAVASCRIPT

ＪＡＶＡＳＣＲＩＰＴ

Javaスクリプト

どれも、前後の文脈も含めて読めば「JavaScript のことだろうな」と想像はつきます。ただ、自分が慣れ親しんだ表記から外れるほど読むときのノイズを感じてしまうのも事実です。読み手としては、なるべくノイズを感じずに文章の意図を読み取ることに集中したいと思います。

また、固有名詞には名付け親がいて、一般公開する文章であれば名付け親の目に触れる機会もけっこうあると覚えておきたいところです。たとえば、日本で開催される技術系イベントの多くは日本人が命名しています。参加レポート等の記事を書いて公開すれば運営の人々にキャッチされて読まれることも多いはずです。命名者からすれば、意図しない形で名前を表記されたとしてうれしくなることはないでしょう。

いずれにせよ、固有名詞を載せるときには「公式サイト等の信頼できる情報を確認する」を実践すればよいだけです。ぼくは自分の記憶や認識をぜんぜん信用していないので、公式サイトの title タグの中身を確認してコピーしてきます。

ソフトウェア開発に通じること

さて、ここまでに 3 つの観点を紹介しました。ぼくがレビュアーを担当するときは、この 3 つの観点をよく活用しています。「ぼくはこう感じました」「こう変えると、どうでしょ？」「別の書き方を検討してみてほしいです！」のようなコメントをよく書いています。少しでも多くの人に快適に読んでもらえるよう、書き手とレビュアーで力を合わせるつもりでやっています。

しかし、ぼくのコメントすべてに対応してもらうまで公開させないぞ！とは思っていません。事実と異なる記述のような致命的なものはレビューのフェーズで Must で対応してもらうとして、今回紹介した観点については Should な性質のものです。それでも書き手に話しかけて対話の機会を設けようとするのは、ソフトウェア開発にもおおいに関わる観点だと捉えているからです。

「文脈とスコープを意識する」は、プログラミングにおける「名前空間」と、その空間における「関数名・変数名」の名付けに関わってきます。File クラスにおける size というプロパティなら「容量」のことだろうな、と読み取ったりします。

「表現したいことと言葉のズレを小さくする」は、モデリングのときに頭を悩ませるトピックでしょう。ソフトウェア上で表現しようとしていることにぴったりの名前が見つかればその後の設計が一気にスムーズになりますし、微妙にズレを感じる名前を採用してしまうと読み解くのが難しくなります。

「モノの名前に意識を向ける」と、そこから派生した「公式情報を参照する」もソフトウェア開発に役立ちます。そもそも、プログラミングにおいては対象の名前を間違えて記述すればコンパイルできなかったりエラーを生じさせたりします。自分の頭の中にある「たぶん、こうだろう」という認識が誤りで、公式ドキュメントを読んだらすぐに解決した…という経験は多くのプログラマが経験していることかと思います。

おわりに

自然言語で文章を書くことと、プログラミング言語でソフトウェアを書くことには、いくつもの共通点を見い出すことができます。そういった考えがあり、ソフトウェアエンジニアが書いた文章をぼくがレビューさせてもらうときは、お互いの成長にもつながるような観点での対話を仕掛けています。