Go to Qiita Advent Calendar 2024 Top
LoginSignup
4
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 3 years have passed since last update.

@kotodu

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

Posted at

はじめに

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

記事テーマの背景

  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

JavaScript

C#(.NET)

Oracle SQL

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/

特徴

使い方

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

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

Stylelint

Language Support for Java(TM) by Red Hat

sonarLint

Super-Linter

  • CI/CDで使用するLinter
    • https://github.com/github/super-linter
    • GitHubActionsというCI/CDのサービス上で動く
    • マージ時に毎回動作し、コーディング規約違反のコードについて、マージを防ぐ

その他Linterについて

コードフォーマッター

概要

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

Prettier

dotnet-format

その他

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

その他ツールの紹介

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

Intellisense

Snipet

おわりに

まとめ

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

参考

4
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
4
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?