はじめに

コーディング規約と各種ツールの自分用メモです

記事テーマの背景

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

主に触れたい内容

コーディング規約の役割、意味
コーディング規約の活用方法(関連ツール)

アジェンダ

はじめに
コーディング規約
関連ツール
おわりに

コーディング規約

コーディング規約の概要

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

コーディング規約の主な内容

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

コーディング規約により可能なこととその目的

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

公開コーディング規約の紹介

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

Java

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がある場合は明記する
単一行・複数行など、ドキュメントコメントを使い分ける

/* 前のバージョンの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

使い方

.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が異なる場合がある

使用方法

設定ファイルを作成する
(コマンドで指摘を行う場合)Lintのプログラムを実行する
(エディターで指摘を行う場合)エディターに対応プラグインを導入する
(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/