読むだけじゃない！コーディング規約

# はじめに
- コーディング規約と各種ツールの自分用メモです

## 記事テーマの背景
1. 改行やコードスタイルの不統一など、プロジェクト内での「もやもや」
2. 何気なく使っているが深く調べていないツールがある
3. 偶然、慣れない言語を使い始めることに

## 主に触れたい内容
- コーディング規約の役割、意味
- コーディング規約の活用方法(関連ツール)

## アジェンダ
- はじめに
- コーディング規約
- 関連ツール
- おわりに

# コーディング規約
## コーディング規約の概要
- 標準としての規約を定義
    - コーディングを誰もが行いやすくする為の文書
- 制作主体はコーディング規約により異なる
    - 言語が提供するコーディング規約
        - Java、Python、PHPなど
    - ライブラリなどが推奨するコーディング規約
        - React、WordPressなど
    - 企業が標準とするコーディング規約
        - Google、Microsoft、Airbnbなど
    - プロジェクトが提供するコーディング規約

## コーディング規約の主な内容
- 名前の付け方
    - 命名記法
        - camelCase,CamelCase,snake_case,SNAKE_CASE...
        - _privateVar,localVar,HungarianInterface...
    - 変数名や処理名の意味(後述)
- コードのレイアウト・スタイル
- 適切なコメントの記述方法
- 言語の使い方の指針とサンプル
- (場合によっては)セキュリティのガイドライン

## コーディング規約により可能なこととその目的
- 見た目の統一
    - 「可読性の向上」
- 他者によるコードの迅速な理解
    - 「保守性の向上」
- 良いコード/好ましくないコードの学習
    - 簡潔で分かりやすいコードの迅速な作成
    - 「品質・生産性の向上」

## 公開コーディング規約の紹介
- 大手企業のコーディング規約が公開されていることもある
    - Google,Oracle,Microsoft,Airbnb

### Java
- Future Enterprise Coding Standards (future-architect.github.io)
    - https://future-architect.github.io/coding-standards/documents/forJava/
- Google Java Style Guide
    - https://google.github.io/styleguide/javaguide.html
    - 有志の日本語訳 : https://kazurof.github.io/GoogleJavaStyle-ja/

### JavaScript
- Google JavaScript Style Guide
    - https://google.github.io/styleguide/jsguide.html
    - 有志の日本語訳 : https://cou929.nu/data/google_javascript_style_guide/
- GitHub - airbnb/javascript: JavaScript Style Guide
    - https://github.com/airbnb/javascript
    - 有志の日本語訳 : https://mitsuruog.github.io/javascript-style-guide/
- スタイルガイド（コーディング規約） - TypeScript Deep Dive 日本語版 (gitbook.io)
    - https://typescript-jp.gitbook.io/deep-dive/styleguide

### C#(.NET)
- C# のコーディング規則 - C# プログラミング ガイド | Microsoft Docs
    - https://docs.microsoft.com/ja-jp/dotnet/csharp/programming-guide/inside-a-program/coding-conventions
- C# at Google Style Guide | styleguide
    - https://google.github.io/styleguide/csharp-style.html
    - 有志の日本語訳 : https://gist.github.com/hideyukisaito/d298075c63b97f56825b0d413d8e4dc5

### Oracle SQL
- Future Enterprise Coding Standards for SQL
    - https://future-architect.github.io/coding-standards/documents/forSQL/

### PHP
- WordPress PHP コーディング規約
    - https://ja.wordpress.org/team/handbook/coding-standards/wordpress-coding-standards/php/

## ピックアップ紹介
- 全て触れるのは現実的ではない 
- 特に重要だと感じた5つを挙げる

### 1. 命名は分かりやすくする
- メソッドの引数とインスタンス変数の名前を一緒にしない
- boolean変数/関数はtrue/falseの状態が分かるようにする
    - `hasOwnProperty`,`isFrozen`,`exists`
- ゲッターメソッドは`get属性名`、セッターメソッドは`set属性名`とする
- 変換メソッドは`toオブジェクト名`とする
- システムハンガリアン記法はインターフェース以外避ける
- メソッドや変数の役割が1つになっているかも重要
    - ローカル変数を安易に再利用していないか
    - メソッド引数への代入をしていないか
    - メソッドが複数の機能を持っていないか

### 2. 無駄なコードを書かない
- 同じコードは2度書かない
    - コピーペーストするような箇所はひとまとめにできないか考える
- 使われないコードは書かない(YAGNI)
    - `You ain't gonna need it.`
    - 「どうせ必要にならない」の意味
    - 機能は実際に必要となるまで追加せず、原則、今必要なもののみコードを書く

### 3. コメントは適切に付与する
- コードを明確にする為にコメントを書き、コードからすぐわかるコメントは省く
    - 変数名をできる限り分かりやすくし、「名前」の説明は避ける
    - 冗長なコメントは避ける
- 必要なものを分かりやすく簡潔に記す
    - 過剰な装飾は避ける
    - TODOがある場合は明記する
- 単一行・複数行など、ドキュメントコメントを使い分ける

```javascript
/* 前のバージョンのAPIは一時的にコメントアウトしている
新バージョンで問題なければ削除する
const getStationsUrl = URL_GET_STATIONS_API_V1;
*/
const getStationsUrl = URL_GET_STATIONS_API_V2;

/**
 * 外部のAPIから駅を取得し、駅名を返す
 * @returns {string[]} 駅名の一覧
 */
const stationNames = fetch(getStationsUrl).then(response=>{
    // レスポンス内容を確認し、駅名のみ抽出する
    // ...(処理)
});

```

### 4. スタイルを見やすくする
- コーディング規約により若干の差異がある
- 命名を分かりやすくすることの他、下記のような点は共通する
    1. 1つの行には1つのステートメント、1つの行には1つの宣言
    2. 演算子前後などでの空白
    3. 字下げなどソースコードのレイアウト
    4. インデント方法はコーディング規約に従う
    5. 長すぎる行は避け、80文字や100文字を超えないようにする

### 5. 権限や安全性が適切か確認する
- スコープやアクセス修飾子は広すぎないか
- 変数と定数の使い分けができているか
- 推奨されない、`@Deprecated`なメソッドを使用していないか

## コーディング規約間の比較
### どのコーディング規約でも共通する箇所
- コードをできる限り見やすくする
    - 命名やロジックは簡潔にする
    - コメントは適切に記述する

### コーディング規約により異なる箇所
- スタイル
    - ハードタブ
        - `\t`...タブ文字
    - ソフトタブ
        - `    `...半角スペース4つ/2つなど
- ネーミング方法
    - 言語により推奨されるものが若干異なる
    - 言語の推奨するものが何か認識することが必要となる
- 言語特有の「似たことができるもの」の使い分け
    - 「配列とリスト」
    - 「varの使い方」
    - 「StringBufferと文字列結合」
    - 「.equals()と==」など

# コーディング関連ツール
## コーディング規約の遵守
- コーディング規約は文書の状態
    - 遵守の為に、慣れるまで日常的に読み直す必要がある
- ツールと連携することでコーディング規約の遵守を行いやすくする
    - コーディング規約を活用し、迅速に開発できる
    - 新たに非推奨となったAPIなど、情報の更新ができる
    - プロジェクト間や言語間で使い分けができる
- ツールを深く調べず無意識に使用していた為、調べなおして共有する

## Editorconfig
### 概要
- 多様なIDE/エディター間でコーディングスタイルを統一する為の設定ファイル+適用機能
    - プロジェクトのリポジトリに設定ファイル配置する
    - 必要に応じて、プラグインを追加し、設定ファイルをエディターに適用する
    - https://editorconfig.org/

### 特徴
- 非常に幅広い言語・エディターが対応している
- 詳細なスタイルの指定はできない
- 一部の言語・エディター固有の設定も可能
    - https://github.com/editorconfig/editorconfig/wiki/EditorConfig-Properties

### 使い方
1. `.editorconfig`というファイルをリポジトリに作成する
2. 設定項目を書き入れ、エディターで開きなおす

### editorconfig設定内容

```editorconfig
# editorconfig.org
# 最優先の設定ファイルかどうか
root = true

# 設定対象を指定するセレクター
[*]

# ソフトタブ/ハードタブの指定(space/tab)
# 半角スペース2つ/4つなど
indent_style = space
indent_size = 4

# 改行コード・文字コードの指定
end_of_line = lf
charset = utf-8

# 行末の空白を削除するかどうか
# 最終行に空白を挟むか
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false

[package.json]
indent_size=2
```

## Linter(Lint)
### 概要
- 静的解析ツール
    - コードから問題を発見・指摘し、必要に応じて修正を行う
    - 指摘方法や修正を行うかどうかは、ツールにより異なる

### 特徴
- 詳細な内容を設定できる
    - プロジェクトに合わせて細部までカスタマイズ可能
- 言語ごとにLinterが異なる場合がある

### 使用方法
1. 設定ファイルを作成する
2. (コマンドで指摘を行う場合)Lintのプログラムを実行する
3. (エディターで指摘を行う場合)エディターに対応プラグインを導入する
4. (CI/CDと連携する場合)Gitのブランチマージ時などにプログラムが警告を表示する

### 設定内容
- 構文やスタイルの問題を指摘する
- 推奨設定をLinterやライブラリが提供することもある
- 注意/警告などレベル分け可能

### ESLint
- JavaScriptのLinter
    - https://eslint.org/
- 非常に豊富なルールをカスタマイズ可能
    - https://eslint.org/docs/rules/

### Stylelint
- CSS/SCSSのLinter
    - https://stylelint.io/

### Language Support for Java(TM) by Red Hat
- JavaについてのLinter + Formatter + Intellisense
    - https://marketplace.visualstudio.com/items?itemName=redhat.java
- vscodeの拡張機能

### sonarLint
- 多様なIDE/多様な言語で使用できるLinter
    - https://www.sonarlint.org/
    
### Super-Linter
- CI/CDで使用するLinter
    - https://github.com/github/super-linter
    - GitHubActionsというCI/CDのサービス上で動く
    - マージ時に毎回動作し、コーディング規約違反のコードについて、マージを防ぐ

### その他Linterについて
- VisualStudioの場合、標準でlinterが組み込まれている
    - https://docs.microsoft.com/ja-jp/visualstudio/code-quality/?view=vs-2019
- VScodeでは、Python/JavaScriptなど既存の言語サポートでLinterやIntelisenseを搭載している
    - https://code.visualstudio.com/docs/python/linting

## コードフォーマッター
### 概要
- 一定のルールに従って、セーブ時などにコードを整形する
    - editorconfigやlinterの設定、またはフォーマッター独自設定に従う

### Prettier
- JavaScript/Yamlなどの有名整形ツール
    - https://prettier.io/

### dotnet-format
- フォーマットに特化した、.NET系言語のフォーマッター
    - https://github.com/dotnet/format/

### その他
- IDEが自動で基礎的な整形を行うこともある
    - VisualStudio,VScodeなどは、editorconfig設定に従い基礎的な整形を行う
- LinterなどがFormatterを兼ねることもある
    - Language Support for Java(TM) by Red Hatなど

## その他ツールの紹介
- コーディング規約の遵守とは少し離れてしまうが、より開発を行いやすくするエディターの機能

### Intellisense
- コードの補完を行う多様な機能
    - メンバーの一覧
    - パラメーターヒント
    - クイックヒント
    - 入力候補
- エディターや言語、その拡張機能などによって要素が異なる
    - VisualStudio
        - https://docs.microsoft.com/ja-jp/visualstudio/ide/using-intellisense?view=vs-2019
    - VScode
        - https://code.visualstudio.com/docs/editor/intellisense
- `@deprecated`となっているか表示が可能
    - Intelisenseの更新により、何が非推奨となっているかなどを知ることができる

### Snipet
- 繰り返しのコードパターンを簡単に入力する為のテンプレート入力機能
    - エディターによっては、Intellisenseと同時に表示され、コードを挿し込むことができる
- エディターによっては、エディターが標準で提供するものの他、拡張機能や、自身での作成も可能
    - VisualStudio
        - https://docs.microsoft.com/ja-jp/visualstudio/ide/walkthrough-creating-a-code-snippet?view=vs-2019
    - VScode
        - https://code.visualstudio.com/docs/editor/userdefinedsnippets
- プロジェクトで頻繁に似た内容を書き込む際は、スニペットを自作すると効率化できる

# おわりに
## まとめ
- コーディング規約によって、簡潔で分かりやすいコードの迅速な作成が可能
    - プロジェクトアサイン時には、あれば確認を行う
    - なければ言語や大企業の提供するコーディング規約に目を通す
- コーディング規約はツールを使い活用可能
    - 日常的な開発効率の向上にも繋がる
- コーディング規約をもとに、気づいた点は少しずつ改善したい

## 参考
- 資料内の各種コーディング規約やWebサイトリンク
- リファクタリング 第二版
    - https://www.amazon.co.jp/dp/B0827R4BDW/
- リーダブルコード ―より良いコードを書くためのシンプルで実践的なテクニック
    - https://www.amazon.co.jp/dp/4873115655/