1. 伊藤 敬彦

2. 準備：プログラマは⽂文書を書く
• プログラマが⽂文書を書く機会は多い
• ⽂文書を書く機会
– クライアントとのメールのやり取り
– 計画書、デザインドキュメント
• 残念念ながら品質に対してあまり気を払われていない

3. 準備：プログラムの記述環境
• プログラムの品質向上への取り組みは美徳とされている
• 品質向上をサポートするツールが揃っている
– CI ツール
– リビジョン管理理 (Subversion、Git)
– 静的コード解析ツール (lint、CheckStyle)

4. 準備：⽂文書の校正環境
プログラムの作成と同様に、⼤大規模な⽂文書の品質をチェッ
クし続けるのは⾮非常に⼤大変
èDocumentValidator を作成
しました。

5. DocumentValidator?
• 技術⽂文書の校正⽀支援ツールとして作成した
• 機能：書いた⽂文書の悪い⽂文を警告する
– 静的コード解析ツール（lint, CheckStyle）的役割を
果たす
• 使い⽅方：技術⽂文書を編集したのち適⽤用する
– コミット、レビューの前

6. 悪い⽂文？
悪い⽂文は⼆二種類ある
1. 理理解を阻害する⽂文
2. フォーマットの不不統⼀一

7. 悪い点：理理解を阻害する⽂文
• ⽂文が⻑⾧長すぎる
• コンマが多い
• 適切切でない表現、単語
– 「〜～〜～することができる」
– 「〜～〜～が可能となる」
– 「〜～〜～と思う」
• ターミノロジー（専⾨門⽤用語）の⾮非統⼀一
– SVM、Support Vector Machine
• 主語が無い

8. 悪い点:フォーマットの不不⼀一致
• コンマの後に半⾓角スペースを⼊入れるか
• アルファベット単語の間に半⾓角スペースを⼊入れるか
• アルファベットは半⾓角か全⾓角か
• 開き括弧の前に半⾓角スペースを⼊入れるか
• コンマ、ピリオド、コロンは全⾓角か半⾓角か
• パラグラフの開始は半⾓角スペース２つか

9. 例例：悪い⽂文書
複数の計算機上で動作 (分散) するアプリケーション、
ソフトウェアが多く存在し、分散ソフトウェアは複数の
計算機で動作することで大量のデータを扱えたり、高負
荷な状況に対処します. 本稿では,複数の計算機（クラス
タ）. で動作する各サーバを「インスタンス」と呼びま
す。
http://www.atmarkit.co.jp/ait/articles/1206/22/
news142.html を一部改編

10. DocumentValidator の使い⽅方
• ユーザは設定ファイルにチェックする項⽬目をリストアッ
プする
– チェックする項⽬目は提供される Validator 集合の中か
ら選択する
• ⽂文書ファイルを⼊入⼒力力として⾛走らせるとチェックする項⽬目
が守られていない場所でエラーを出⼒力力してくれる

11. 例例：設定⽅方法
<configuration name="Validator”>
<component name="SentenceIterator”>
<component name="SentenceLength”>
<property name="max_length" value="50"/>
</component>
<component name="InvalidExpression">
<property name="dictionary" value="dic/invalid_word.dic"/>
< /component>
<component name="SpaceAfterPeriod" />
<component name="InvalidCharacter" />
<component name="SpaceWithSymbol" />
</component>
<component name="SectionLength">
<property name="max_char_number" value="50"/>
</component>
<component name=“ParagraphNumber" />
</configuration>
文の長さをチェック。
シンボルの前後にスペー
スがあるかをチェック
使うべきでない文字が使
用されているかをチェッ
ク

12. 参考: CheckStyle の設定ファイル
<module name="Checker">
<module name="JavadocPackage"/>
<module name="NewlineAtEndOfFile"/>
<module name="Translation"/>
<module name="FileLength"/>
<module name="EmptyForIteratorPad"/>
<module name="GenericWhitespace"/>
<module name="MethodParamPad"/>
<module name="NoWhitespaceAfter"/>
<module name="RegexpSingleline">
<property name="format" value="s+$"/>
<property name="minimum" value="0"/>
<property name="maximum" value="0"/>
<property name="message" value="Line has trailing spaces."/>
</module>
</module>

13. サポートしている Validator
• ⼀一⾏行行単位の Validator
– SentenceLength
– CommaNumber
– InvalidWord, InvalidExpression
– SuggestExpression
– SentenceStartWith
– WordNumber
– WhiteSpace
– SimbolValidator
• Section 単位の Validator
– ParagraphLength
– ParagraphNumber
– ParagraphStartWith

14. 直近でサポート予定の Validator
• DuplicateWord - ⼀一⽂文に同⼀一の単語が⼤大量量に出てくる
のを検知する（英語の “of”、⽇日本語の “の” 等）
• ListNumber – リストの要素数に制限を加える
• Reference – 引⽤用がちゃんと存在するかを調べる

15. サポートしているフォーマット
• テキスト
• Wiki 記法

16. 今後の予定
• Validator のプラグイン化
• サーバー化 & UI 追加
• 抑制アノテーション
• ⾔言語毎に実装が異異なる Validator を加える
– 英語の三⼈人称単数現在、時制、代名詞
• ⾔言語毎の設定テンプレート
• Eclipse、IntelliJ IDEA から利利⽤用したい
• サポートする⽂文書フォーマットの拡充: RST、
MarkDown

17. 現在までの所感
• ⾃自分が使いたいものになりそうな予感はしてきた
• 週末コーディングは良良い気分転換になる

18. まとめ
• 現在作成中の DocumentValidator のご紹介をしました
• 近々公開します

19. 最後に
コメントくれた⽅方ありがとうございました。
– PFI 秋⽥田さん、岩⽥田さん、岡野原さん
– 東京都⽴立立⼤大学 ⼩小町さん