【メモ】資料・仕様書・コーディングをする際の自分ルール(可読性)

プログラムの読みやすさ、重要ですよね。

わかりやすい仕様書・資料、大事な資産ですよね。

『プログラムが動けばよい』『納品すれば良い』『記載しておけばよい』というのは、その場限りでいえば正義かもしれませんが、後日の保守・運用側からすると最悪最低な行為です。過酷な作業環境で開発していたのであれば一考の余地はありますが・・・

 今回は品質を担保するため(アウトプットのブレをなくすため)に律しているルールを記載していきたいと思います。
※基本的なことも書いてあったり、書いてなかったりします。これ以外にも守っていることはあるのですが、守ってるけど思い出せないものがあるので追記していく予定です。

 １．仕様書・資料作成をする際に注意していること  　

• 見せる相手を意識すること.資料は今後管理され、後任者が読むことを意識すること
• 色による説明は色盲の方を考慮し行わない(現在はいなくても関連する部署や今後入ってきた人を考慮する)
• 理解しやすい資料を作成するため色を含めた表現を行うこと(色だけで意味を表現しない) 　また、無意味な色の設定を行わないこと.
• 概要では"ぱっと見"で伝えられる情報を意識すること. 
• 文章の長さを意識すること. 長文は箇条書き等で分割する. 
• 概要説明等、必要に応じて図・表での表現を取り入れること.
• 概要を説明してから詳細を記述すること. 全体像の説明してから部分の説明をすること.　
• 章構成は意識すること. 章項目 について目立たせること(太字にする・文字の大きさを変える・段落を分ける)
• 仕様書を変更する際はバージョン管理をし、変更前の内容を仕様書には残さないこと(変更前を確認できる状態を保持すること)

２．コーディングをする際に注意していること　　　

分類	内容
メソッド	名称は 動詞 ＋ XXXXX で統一すること
メソッド	名称は 動詞＋名詞 の順で規定すること。 名詞 ＋ 動詞 とはしないこと。
メソッド	目的をはっきりともち、一つの目的を達成するための処理を記載すること。目的以外の処理は記載しないこと。
メソッド	1つのメソッドに記述する分量を考慮すること。100行(？)程度を目安とし、必要に応じて処理をメソッド化すること
メソッド	同一処理を複数メソッドに記述しない
メソッド	処理はブロック単位で連続性をもたせて記述すること. 例：”① メソッドを実行 ②変数にユーザ入力情報を格納する ③ ①のメソッド結果をチェックする ”の場合、 ②の処理を ①の処理の前で実行する。 ③ で""①の結果 と ②の値をチェックする"" 場合はこのままでよい。"
変数	名称は動詞を使わないこと。形容詞, 名詞を利用すること
変数	名称はメンバ変数・ローカル変数がすぐに理解できるようにしておくこと
変数	格納値にジャンルやステータス等、決まった値を入れる際、null に意味を持たせないようにする. 例：○ 1:円, 2:ドル, 3:ウォン, 4:元　× 1:円, 2:ドル. 3:ウォン, 4:元, null:ユーロ"
コメント	理由・目的を記述すること。処理説明は基本的にはしない。 メソッド内で処理をブロック化した際へのコメント等はつけても良い
コメント	XMLドキュメントは記述すること
全体	クラス名・メソッド名・変数名…etc において名称は"意味が推測できる"こと。 省略語を使わなず、かつ、長すぎないこと。※要するに悩め・考えろ。"
全体	１行あたりの文字数を考慮すること。横に長いとスクロールが発生し可読性が落ちる。 100字程度で区切ることを検討すること
全体	インデントは合わせること