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年1月15日 (水)

並列の「たり」

単独で使うケースもあり。[新]

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

[ スタイルガイド ]

[ 1月15日全て ]

2020年7月16日 (木)

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

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

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

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

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

[ 7月16日全て ]

2021年1月7日 (木)

片仮名複合語と中黒 #nNote

なかぐろ。中点(なかてん)。

例外はありとしつつ「姓名の間に中黒」「2語の複合語なら入れない」「3語以上の複合語なら入れる」「固有名詞と普通名詞の組み合わせなら入れる」が優勢か。

平成三年 内閣告示第二号 「外来語の表記

複合した語であることを示すための,つなぎの符号の用い方については,それぞれの分野の慣用に従うものとし,ここでは取決めを行わない。

記者ハンドブック第13版 p.118

人名について:

2 外国人(漢字名を除く)の名と姓の間、「サー」などの継承と姓名の間には中点を使う。

外来語について:

3 外来語、外国の地名、建造物名称などは原則として中点を入れない。

ただし次の場合は中点を入れる。

  1. 固有名詞と普通名詞からなる語
  2. 3語以上からなる語
  3. 長くて判別しにくい語

毎日ことば

カタカナ語を「・」で区切るときの原則 | 毎日ことば

  • 2語からなる複合語は原則として語間に中黒をつけない。
  • 3語以上からなる複合語は原則として語間に中黒をつける。
  • 固有名詞と一般外来語とが複合する場合は中黒をつける。

『JTF日本語標準スタイルガイド(翻訳用) 第3.0版』 2.1.7 カタカナ複合語

https://www.jtf.jp/...

中黒または半角スペースを用いてカタカナ語を区切って表記します。

固有名(外国人名)の区切り方法は、一般カタカナ複合語の区切り方法とは別に定める必要があります。通常、固有名(外国人名)の区切りには中黒を使います。

文章・用字用語ハンドブック

テクニカルコミュニケーション研究会編、文章・用字用語ハンドブック、日経BP出版センター

入れ方は、マニュアルの性格や会社の方針を考えて決めます。

[ Naney のスタイルガイド ]

[ 1月7日全て ]

2021年2月5日 (金)

『JTF日本語標準スタイルガイド(翻訳用)』 #nNote

文書内では「JTFスタイルガイド」と略記されている。

丸括弧と前後の空白 (第3.0版より)

  • (いわゆる)丸括弧には全角文字を使う。 (3.3.1 より)
  • 括弧の外側・内側どちらにもスペースを入れない。 (2.3.2 より)

[ Naney のスタイルガイド ]

[ 2月5日全て ]

About Me

Naney Naney

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

About nDiki

nDiki1999年1月に始めたコンピュータ日誌を前身とする NaneyWeb 日記(兼パーソナルナレッジベース)です。

#nNote タグがついている記事は他の記事に比べて、より断片的・未整理・不完全なちょっとしたノートです。まだ結論に至っていない考えなども含まれます。頻繁/大幅に更新したり削除したりすることがあります。

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

Other Notes

ナレッジベースアプリケーション Obsidian で書いているノートの一部を notes.naney.org で 公開しています。

月別インデックス
Process Time: 0.14833s / load averages: 0.54, 0.71, 0.72
nDiki by WATANABE Yoshimasa (Naney)
Powered by DiKicker