nDiki : スタイルガイド

スタイルガイド (style guide)

スポンサード リンク

2005年3月30日 (水)

わかりやすいマニュアルを作る 文章・用字用語ハンドブック

わかりやすいマニュアルを作る 文章・用字用語ハンドブック [ コンピュータ書籍 ]

今日の作業で今年度の作業に区切りがついて一段落。 (いつものことだが)マニュアルについては後手にまわってしまって完成度の高さが十分ではなかったと反省。

いや、時間だけの問題ではないな。 考えてみれば、テクニカルライティングのイロハをきちんと学んでいない。 自分で書くにしても他人が書いた物の問題の指摘をするにしても、これはいけない。

それから、電子マニュアル化ソリューションを提供するなんて言うのに「マニュアルとはなんぞや」を学んでいないなんて恥ずかしい。 Webベースソリューションを提供する企業のWebサイトが駄目駄目なのが恥ずかしいのと同様。

ということでまずは書籍をチェック。 まずは評判の良い「わかりやすいマニュアルを作る 文章・用字用語ハンドブック」を手にしてみた。 主にコンピュータ業界を対象にした内容になっているが、書泉ブックタワーではコンピュータ書籍のフロアではなく1階上のフロアに置いてあった。

冒頭で

この本は、この本で示したルールに従って書いています。p.iii

と書かれている。素晴しい。 X言語で書かれたX言語処理系とか、そういった自己記述・自己適用の好きな自分のハートをがっちりキャッチされた。

まずマニュアル作成工程

  1. 企画
  2. 目次の作成
  3. アウトラインの作成
  4. レイアウトの決定
  5. 執筆規則の作成
  6. 執筆と推敲
  7. 査読とテスト

の概要が解説されている。 この点からして頭の中で整理されていなかった部分があるので有り難い。

さすが、読みやすく書かれているのでさらりと読めそうだ。

[ 読書ノート ] [ お薦めの本 ] [ スタイルガイド ]

スポンサード リンク
[ 3月30日全て ]

2009年8月20日 (木)

アクセサは foo と set_foo にしたい

オブジェクト指向プログラミングではほとんどの場合に必要となるアクセサについては命名規則にいくつかのパターンがある。

  1. 属性名に対して getter に get (get_)、setter に set (set_) をプレフィックスとしてつける。
  2. getter も setter も同じ名前とし属性名にする。
  3. setter のみ set (set_) を属性名にプレフィックスとしてつける。

1 番目は Java プログラミングでよく使われる。 またそれ以外でも広く使われている形式だ。 get と set 命名規則的に対になっていて規則的には美しい。 getter と setter を別々に検索するのも用意だし、プログラミング時にも誤解を招きにくい。

ただし例えば x、y、z のような短い名前の属性の取得の場合 obj->get_x などと、うるさい感じになってしまう。また obj->get_foo->get_var なども obj->foo->var などに比べてすっきり感がない。

2 番目は Perl でよく使われる。C# のプロパティへのアクセサは getter と setter が同じ名前になる。 呼び出し側ではコードが短くなりすっきりする。

ただし Perl の場合は引数の数を動的にチェックするために効率が若干犠牲になるのと、setter の機能が無いアクセサに引数を渡してもエラーにならないため見逃しやすいバグが潜んでしまう可能性があるなどの問題もある。Perl ベストプラクティスではこの形式ではなく1番目の形式を勧めている。

3 番目はあまり多くないかな。 getter に get がついていると個人的には重い印象を感じる。 getter を属性名だけにすることですっきりするとともに、setter は set_ と動詞がつくことでオブジェクトに働きかけるという印象を残すことができる。

命名規則が非対称なのでちょっと気持ち悪いといえば気持ち悪い。

Google C++ スタイルガイドではこの形式を採用している。

個人的には3番目がコードの見た感じにもすっきりしていて読みやすく、また getter と setter の区別も(1番目ほどではないにせよ)つきやすいので良いのではないかと思う。 2番目もよく使っていたのだが、しばらく3番目にしてみようかと思った今日このごろ。

[ 8月20日全て ]

2011年2月1日 (火)

今日のさえずり: 昔は例外処理を好んで使っていたが、最近はできるだけ使いたくない派

2011年02月01日

  • 08:05 明日 9:15 で病院予約した。花粉症もらいにいく。
  • 09:31 Wi-Fi に対応したspモードメールアップデート中。 #Xperia
  • 09:37 完了。Wi-Fi 設定はあ・と・で。 #Xperia
  • 09:59 GPS での測位、今日は東にだいぶずれてるな。端末の問題? #Xperia
  • 10:05 あ、良くなってきた。
  • 10:45 プリンタ保守のエンジニアから電話修理難航中でまだしばらくかかりそうとのこと。いったいどんな不具合だったんだろう。
  • 11:59 Google アカウント1つ潰した。
  • 12:07 弁当 350円。 (@ 向日葵 和泉町店・カレー食堂) http://4sq.com/eLgExR
  • 12:18 「40前後で『ガールズトーク』と言うのはいかがなものか」ってにいったら、いいんだって言われた。「セックス・アンド・ザ・シティ」が何たらとか説明された。ということでアリらしいです。
  • 13:32 REGZA Phone T-01C 買った同僚に K-9 Mail 薦めた。 #Android
  • 13:33 Google アカウントもう1つ潰した。
  • 17:07 spモードメール、バックグラウンドで送信できるようになったんだ。これは大きな進歩。 #Android
  • 18:52 コーディング規約内の心得に「サンプルを鵜呑みにしない」と書いてあるのだが、その後コーディング規約内にサンプルが出てくるので心がザワザワする。
  • 19:01 昔は例外処理を好んで使っていたが、最近はできるだけ使いたくない派。
  • 19:09 @wtnabe 開発が進むにつれて、どんな例外が throw されてくるかが次第に自明で無くなってくるから。
  • 19:16 @gnue 開発が進むにつれて、どんな例外が throw されてくるかが次第に自明で無くなってくるから。
  • 19:21 Joel Spolsky の「間違ったコードは間違って見えるようにする」に例外処理について書かれているけど、だいたいその主張に近い。
  • 19:24 Google C++スタイルガイドC++ の例外を使わない派。
  • 19:27 More Joel on Software に収録されてる。 http://amzn.to/eARt3t RT @Naney: Joel Spolsky の「間違ったコードは間違って見えるようにする」に例外処理について書かれているけど、だいたいその主張に近い。More Joel on Software
  • 19:36 呼び出し先を全部辿らないとどんな時に何が throw されてくるかわからないし、ここで throw するようにすると全ての呼び出し元できちんと catch されるのかも全部辿らないといけない。
  • 19:42 ドキュメンテーションコメントにおいてメソッドが何を throw するかってのも最初は書いてみるけど破綻するよね。
  • 20:18 K-9 MailGmail からプッシュするフォルダを INBOX フォルダから重要フォルダに変えてみた。優先トレイがきちんと学習してくれれば、ちょっとしたニュースレターとかでの通知が減るはず。 #Android
  • 20:20 INBOX の同期間隔は長めに変更。 #Android
  • 21:52 spモードパスワードって何だ。
  • 21:53 わかった。あれだ。
  • 22:03 Wi-Fi 接続でのspモードメールの送受信を確認。 #Xperia
  • 22:24 先週の水曜日に爪が折れていて皆が困っていた(と思われる) LAN コネクタを直したんだけれども、誰も「いいね!」って言ってきません。計算機管理チームとはそういうものです。
  • 24:25 X-Face 懐かしい。Sylpheed だと今でもちゃんと表示されるんだ。
[ 2月1日全て ]

2011年2月2日 (水)

例外処理機構は刃物だ

More Joel on Software

昔は例外処理機構(try で catch で throw、throw)を好んで使って設計・実装していたが、最近はできれば使わない方がいいかなと思っている。 あれは刃物だ。気違いに刃物だ。宇宙戦艦ヤマトだ。

全体が見渡せるか管理下における規模のプログラムでは有効だが、そうではない場合はあれはヤバイ。面倒。そして落ちる。

Joel Spolsky の More Joel on Software「間違ったコードは間違って見えるようにする」に例外処理について書かれているけど、理由としてはだいたいその主張に近い。

Google C++スタイルガイドC++例外処理機構を使わないとしている。

呼び出し先から一体何が throw されてくるのか?

呼び出し先ツリーを全部辿らないとどんな時に何が throw されてくるかわからない。

ドキュメンテーションコメントにおいてメソッドが何を throw するか説明されているからそれを見ればいい? それって信用できる? 自分は今書いているメソッドの呼び出し先で throw される可能性のある例外とメソッドで throw する可能性のある例外を、そのメソッドのドキュメンテーションコメントに毎回きちんと書いてる? コードの変更を反映させてる?

え? throws clause?

呼び出し元できちんと catch してくれるの?

今書いているメソッドで、例外を throw したくなった。 でもこれってきちんと catch されるの? 呼び出し元ツリーを全て確認して、必要があれば catch を追加しなければならない。さもなけらば……落ちるよね。

え? とりあえず全ての型を catch して中の例外処理が空になっているそのブロック何?

ということで

例外処理機構を使うと、頻繁に深くコードをチェックしなければならなくなる。

いや便利だしスマートに書けるし、言語/ライブラリ的に使わざるを得ない時もあるし、使う時は使うけどね。

die;

[ 2月2日全て ]

2015年12月3日 (木)

新しい文章力の教室 苦手を得意に変えるナタリー式トレーニング

新しい文章力の教室 苦手を得意に変えるナタリー式トレーニング

以前株式会社ミクシィで広報だった方が「新しい文章力の教室 苦手を得意に変えるナタリー式トレーニング」という本を Facebook で薦めていたので読んでみました。

文章を書く準備段階の「構造を考える方法」、そして「読みやすく分かりやすい文章に仕上げていく方法」が本書で解説されています。

構造シート

第1章では「構造シート (p.34)」を使って「テーマ」と「話題」を決めていくやり方を説明しています。「話題」を箇条書きで列挙し、それを眺めて「テーマ」を決定する。次に「話題」の順番を考えて左に数字を書く。そして番号順に「話題」を並べ替えたあと「話題」の右側に3段階の優先度を ABC を書くという流れでまとめていく方法です(このあと「話題」の取捨選択がきます)。

きちんとアウトラインを決めるべきと思いつつも、上からざっと書いていって質の低い文章を書きがちなのでこれは実践していきたいです。

良い文章

続く2章以降では基本的な文の構造の正しさの話から文末のバリエーションや漢字と平仮名のバランスなどの読みやすさの話まで網羅的に説明されています。個別には文章術などのコラムなどでみかけたりしますが、こうしてまとまっていると振り返って参照しやすく助かります。ここはチェックシート化して普段からチェックしたいところです。

例えば「することができる」などの「翻訳文体」はつい書いてしまいがちなので、これを機会に意識していくことにします。

日本語の作文技術」で学んで推敲の際にはよく基準にしている「係り受けの距離を近づける」「修飾語句は大きく長い順に」もきちんと説明されていますので、これから日本語書き方について本を推薦するなら本書が良いと感じました。

お薦めの1冊です。

[ 読書ノート ] [ お薦めの本 ] [ 文章技術 ] [ スタイルガイド ]

[ 12月3日全て ]

2020年7月16日 (木)

ライティングアプリ iA Writer のスタイルチェックを活用する

ライティングアプリ iA Writer 5.6 でスタイルチェック(Style Check)機能がついた。現時点でビルトインされたパターンは英語・フランス語・ドイツ語のみで日本語は含まれていないが、環境設定からカスタムパターンが追加可能である。試しに「新しい文章力の教室 苦手を得意に変えるナタリー式トレーニング」(紹介)を参考に以下のパターンを追加してみた。

  • という
  • ことができる
  • できる。
  • 基本的に
  • 一般的に
  • となる。
  • となった。

文章を書いていてこれらのパターンが出てくるとエディタ上で打ち消し線表示される。「という」は結構使っているようで、書いた瞬間に打ち消し線が入って「あっ」と何度もなった。過去の記事でも「という」が頻出していた。無意識のうちに使いがちな避けた方が良いパターンにすぐ気付けるのいいね。徐々にパターンを増やしていきたい。

[ 文章技術 ] [ スタイルガイド ]

[ 7月16日全て ]

About Me

Naney Naney (なにい)です。株式会社ミクシィで SNS 事業の部長をしています。

nDiki1999年1月に始めたコンピュータ日誌を前身とする NaneyWeb 日記(兼パーソナルナレッジベース)です。ちょっとしたノートは nNote にあります。

※内容は個人的見解であり所属組織とは関係ありません。

月別インデックス
Process Time: 0.066874s / load averages: 0.26, 0.46, 0.52
nDiki by WATANABE Yoshimasa (Naney)
Powered by DiKicker