コーディング規約を作ろう

コーディング規約やスタイルガイドは、HTMLやCSSのマークアップや、各種プログラミング言語の書き方をまとめたものです。コーディングスタンダードやコーディングガイドラインとも呼ばれますね。コーディング規約を決めていなかったり、あいまいにしたまま進めていくと、書式が統一されていないため、コードを追加すればするほどゴチャゴチャしたコードになりがちです。チームでコーディングしていくならなおさら。今回チーム用のコーディング規約を見直すことになったので、その時感じた抑えておくべきポイントをまとめてみます。

LETS

コーディング規約に含むべき項目

ディレクトリー階層

ファイルを保存するフォルダーの階層や、そのフォルダーの名前を決めておきます。画像を格納しているフォルダーを例にあげても、「image」「images」「img」などの名前が考えられます。人によってつけるフォルダーの名前が変わってしまうと管理しづらく、ミスが増えてしまいます。


画像を使って階層と各ディレクトリーの解説をしている規約例。

共通ファイル

どのサイトでも使う共通ファイルについて整理しておきましょう。それらのファイルは「template」や「common」など、わかりやすい名前のフォルダー内に保存し、他のファイルと混同しないようにします。

フォーマット

インデントはタブを使うのか?カラーコードは小文字?などなど、細かい書き方を決めておきます。ちょっとしたことかもしれませんが、チームでコーディングしていくのであれば全て統一しておいた方が管理も楽になります。

  • インデント(タブを使うのか?スペース2つなのか?一切インデントしないのか?)
  • カラーコードは小文字?大文字?
  • コメントの書き方
  • プロパティーの記述順
  • シングルクォート(”)?ダブルクォート?(””)
  • サイズの単位(px? em? %?)

Googleのガイドライン例
特に間違えやすい部分は具体的に良い例と悪い例をあわせて記載することで、よりわかりやすくなります。

コメントの書き方例
コメントフォーマットの例。CSS、JavaScript、PHPなど、言語ごとに分けるか、統一するかも考えておきましょう。

命名規則

ID、クラス、引数、関数、ファイル名等の命名規則を統一しておくと、自分が名付ける時にも迷わなくなります。他のメンバーが見てもすぐになんの要素のことなのかがわかるよう、明確な名前をつけます。名前のフォーマットは、例えば news item という名前をつけたい場合、

  • news-item
  • news_item
  • newsItem

など、書き方は様々。後で修正する手間を省くためにも予め決めておきましょう。

WordPressサイトのコーディングガイドライン例
PHPの命名規則の例。キャメルケース (camelCase)は使わない、単語はアンダースコアで分ける、クラス名は先頭大文字…などと設定しています。

対応ブラウザー

対応させるブラウザーはプロジェクトによって変わってくる場合が多いですが、基本的に対応させるのはどのブラウザーなのかをまとめておくといいでしょう。同じサイトでもページによって(コーディングする人によって)表示されるブラウザーやバージョンが異なるという事態を防ぐことができます。また、「うちの制作するサイトはこのブラウザーに対応しています」という指標があると、ディレクターや営業さんと制作チームとの認識のズレもなくなります。

コーディング規約の実例

公開されているコーディング規約やスタイルガイドです。他にも公開している企業はいくつかあるので、検索してみてください。

Google

Google HTML/CSS Style Guide
GoogleによるHTMLとCSSのスタイルガイド。いい例・悪い例がわかりやすくまとめられています。とにかく細かく、具体的に書かれているので、規約の作成時に一読しておくといいかも。

日本語→ 「Google HTML/CSS Style Guide」を適当に和訳してみた

Github

Github Styleguide
Githubで紹介されているコーディング規約。CSSだけでなく、JavaScriptやRubyのコーディング規約も。

WordPress

WordPress Coding Standards
WordPressのコーディング規約。CSS、HTML、JavaScript、PHPの書き方をまとめています。

日本語→ WordPress コーディング基準 – WordPress Codex 日本語版

日本語で読めるその他言語のコーディング規約は「プログラマのための言語別コーディング規約まとめ」にまとめられているので、覗いてみてください。

コーディング規約を管理

基本的にバージョン管理できるサービスにはWiki機能が搭載されていると思うので、そちらを使うと管理が楽かなーと思います。

Github

Github wiki
バージョン管理にGithubを使っているならこちらのWikiを使うとよさそうですね。規約用のリポジトリーを作成し、README.mdに記載してもOK。非公開にするには有料アカウント必須。マークダウン記法対応。

Githubを使ってコーディング規約を公開している例:

Bitbucket

Bitbucket
Bitbucketは無料アカウントで非公開リポジトリーを作成できるので、コーディング規約を非公開にしたい場合はバージョン管理もあわせてBitbicketを使うとよさそうです。マークダウン記法対応。

DAUX.IO

DAUX.IO
DAUX.IOはフォルダー階層とマークダウンファイルを使って作成できる、シンプルなドキュメントジェネレーター。作成するコーディング規約の種類が多い場合は1ページで収めきれないと思うので、このジェネレーターで階層をわけてまとめるといいですね。

Style-Guide-Boilerplate

Style-Guide-Boilerplate
Style-Guide-Boilerplateを使えばカラーコードや見出し、ボタンなどのベーススタイルをまとめたスタイルガイドが作れます。ソースコードだけでなく、実際にそのスタイルが反映されるので、視覚的にもわかりやすいです。日本語での解説は「ウェブサイトの制作に携わる全ての人に役立つスタイルガイドを簡単に作成できる -Style Guide Boilerplate」がわかりやすいです。スタイルガイドなので、プロジェクトごとにまとめておけますね。

マークダウン記法

さきほどからちょいちょい出てくるマークダウン記法とは、テキストを手軽に装飾するための書き方です。装飾と言ってもどれが見出しで、どれがリストで…といった文書構造をわかりやすくするためのもので、とても簡素作りとなっています。HTMLマークアップをしなくても、ちょっとした法則にのっとって記述していくだけで自動的にHTMLとして変換されるので、プラグイン等に含まれる README ファイルのような簡単な説明書きに広く使われています。

詳しい説明は「README.mdファイル。マークダウン記法まとめ」がわかりやすかったです。

Github Preview
マークダウン記法をリアルタイムでプレビューしてくれるGithub Previewというサービスもあります。実際に試してみると、マークダウン記法の使いやすさに感動しちゃいますよ!

まとめ

コーディング規約を作成することよりも、チーム全体でその規約を守ることの方が難しいかもしれません。しかし、制作チームの規模が大きくなればなるほど、コードの統一性は大切です。誰が見てもわかりやすいコーディングを目指し、予め決めておける点はまとめておくと捗りますよ。他にもコーディング規約を作成時に考慮すべき点があれば教えてください :)

シェアする

コメント

“コーディング規約を作ろう” への6件のフィードバック

  1. […] コーディング規約を作ろう | Webクリエイターボックス […]

  2. […] category: 世の中意味不明な値段交渉ルート営業をしてるんだが、いつも値引きを要求されないお客さんから値引きを要求された。だから品質を落としたり品数を減らす提案をしたんだが、品数や品質は落としたくないという。しかも、客側の意見としては「これまでうちと取引して値引きできる部分もあるでしょ?」ときた。あるわけがない。値引き率は1/4だ。破格だ。他に下げられるとしたら、俺らの人件費ぐらいだ。 だから、「御社がお客様の仕事をする時、1回目でも…bookmarks: 80category: 暮らし佐藤秀峰×佐藤智美 「離婚インタビュー」前編:少年 佐藤秀峰:佐藤秀峰チャンネル – ニコニコチャンネル:エンタメ少し前の出来事ですが、僕と佐藤智美は12年間の結婚生活に終止符を打ちました。 離婚の前日は結婚記念日でした。 とても晴れた天気の良い日曜日で、僕は息子に新しい自転車を買ってあげたばかりだったので、家族3人でサイクリングに行こうということになりました。 多摩湖自転車道を始点の関前5丁目から多摩湖まで約12キロ。 2時間かからずに多摩湖に到着し、隣接する西武園遊園地へ。 お昼は持参したお弁当を食べ、い…bookmarks: 394category: 暮らし生ビール30円…? お酒が安すぎる謎の居酒屋グループがある – NAVER まとめ松ちゃん、アルプス、やまと、めだか、竹子、ぼたん…。これだけ聞いてピンとくる人も多いはず。名前に規則性がなく、店構えもバラバラで、しかしビール・ハイボールが超安い、謎の居酒屋グループが都内に点在するのです。各店舗の共通点はドリンクの安さとカラフルなメニュー。どんな店があるのかまとめました。 更新日: 2013年07月30日RSSbookmarks: 426category: テクノロジーラグナロクオンラインは既にどうやって最期を看取るかと言う段階 – Life like a clownWebパズル&ドラゴンズ(パズドラ) で絶好調のガンホー社ですが、その一方で、かつてのメインコンテンツであった ラグナロクオンライン(RO) が悲惨な状況となっています。下記は、jRO の接続人数を書き写すスレ にて毎日 23 時に定点観測されているものから 毎年 7 月最終週の日曜日のものを抜粋したものですが、ここ数年、接続人数の減少に歯止めがかからず(今年に入ってから特に酷くなっている)、もは…bookmarks: 297category: 世の中土屋アンナの面白舞台で抗争案件(山本 一郎) – 個人 – Yahoo!ニュース山本一郎です。雨が降るのか降らんのかはっきりしやがれ。 ところで、昨日から芸能界方面のニュースが炎上して賑わっております。 土屋アンナさん、無断で稽古不参加 初主演舞台中止に 主催者側は法的措置も検討(産経新聞 2013/729) 土屋アンナさんの初主演舞台、公演中止 主催者が発表(朝日新聞 2013/7/29) 流れとしては、当初は舞台主催者側が出演者の非を一方的に申し立て、それを理由に公演中止…bookmarks: 181category: テクノロジー朝日新聞デジタル:NEC、レノボへ携帯事業売却を断念 多額損失のおそれ – 経済・マネー【上栗崇】携帯電話事業からの撤退を決めているNECが、中国・レノボへの事業売却を断念したことが30日わかった。レノボが興味を示している特許や海外拠点などの資産だけを売り、残った資産や人員は他の事業に転用するなどNECが自前で整理する。リストラで多額の損失が出るおそれがある。  レノボ側から29日、携帯事業を手がける子会社の買収を断る回答が届いたという。レノボが2011年にNECから買収したパソコン…bookmarks: 43category: アニメとゲーム改札機に切符粉砕されたお話→「絶対にありえない」 – Togetterフォロワーが体験した事が無さそうな体験というタグにて投稿されたツイートに対して「絶対にありえない」と異を唱える東鉄DJ指令氏 それは本当に絶対にありえない出来事なのか? by towatotowatobookmarks: 56category: おもしろイチローの通算状況別打率wwwwwwwwww :日刊やきう速報@なんJhttp://hayabusa.2ch.net/test/read.cgi/livejupiter/1375110506/ 1: 風吹けば名無し 2013/07/30(火) 00:08:26.53 ID:jZTszUZg 通算打率 .320 ランナーあり打率 .321 得点圏打率 .320 ホーム打率 .321 ロード打率 .320 0アウト時の打率 .321 1アウト時の打率 .320 2アウト…bookmarks: 132category: エンタメ小学生に「パンツ脱げば100点」 寺のゲームで全裸に (朝日新聞デジタル) – Yahoo!ニュース大分県津久見市の寺が開いた小学生向けの合宿で、パンツを脱げば高得点を与えるルールのゲームをしていた。男女合わせて約20人が全裸になったという。保護者の抗議を受けて寺は27日に説明会を開き、謝罪した。取材に「子どもは喜んでいると思っていた。認識が甘かったと反省している」と話している。 合宿は22〜23日の1泊2日。寺を母体とする学校法人が運営する幼稚園の卒園生が対象で、1〜5年生59人が参加した。 …bookmarks: 46category: 政治と経済自民・脇氏「輿石氏は副議長に不適任」 NHKニュース自民党の脇参議院国会対策委員長は、党の役員会で、新しい参議院副議長に推す意見が出ている民主党の輿石参議院議員会長について、「極めて不十分な国会運営を行った責任者が副議長に選任されていいのか」と述べ、副議長に不適任だという認識を示しました。 先の参議院選挙を受けて来月2日に召集される臨時国会では、新しい参議院議長は第1党となった自民党から、副議長は第2党の民主党から選出される見通しで、副議長を巡って…bookmarks: 26category: 暮らし伝説のネタ画像「女性専用車両インタビューの女」は今、女性専用車両についてどう思っているのか? – ねとらぼこんにちは。セブ山です。 みなさんは、こちらの画像を見たことはあるでしょうか? 2ちゃんねるによく貼られるネタ画像のひとつで、さまざまなタイプの女性が女性専用車両についてのインタビューに答えているものです。 そんな画像の4コマ目で「私は特に、どこでもいいです」と答えている彼女の正体が、最近になってようやく分かったと話題になっています。 過去のねとらぼ記事(ネットで有名な『女性専用車両インタビューの…bookmarks: 367category: エンタメ朝日新聞デジタル:小学生に「パンツ脱げば100点」 寺のゲームで全裸に – 社会大分県津久見市の寺が開いた小学生向けの合宿で、パンツを脱げば高得点を与えるルールのゲームをしていた。男女合わせて約20人が全裸になったという。保護者の抗議を受けて寺は27日に説明会を開き、謝罪した。取材に「子どもは喜んでいると思っていた。認識が甘かったと反省している」と話している。  合宿は22〜23日の1泊2日。寺を母体とする学校法人が運営する幼稚園の卒園生が対象で、1〜5年生59人が参加した。…bookmarks: 195category: 学び「死」は青い光を放つことが判明 « WIRED.jpTEXT BY LUC HENRY IMAGE BY WELLCOME TRUST TRANSLATION BY MINORI YAGURA, HIROKO GOHARA/GALILEO ARS TECHNICA (US) 生きている状態(左側)と、死の状態(右側) 「ブルーな感じ」という言葉が、これほど決定的な意味を持ったことはなかった。新しい研究によって、線虫が死ぬときに青い光を放つことがわか…bookmarks: 198category: テクノロジーコーディング規約を作ろう | Webクリエイターボックスコーディング規約やスタイルガイドは、HTMLやCSSのマークアップや、各種プログラミング言語の書き方をまとめたものです。コーディングスタンダードやコーディングガイドラインとも呼ばれますね。コーディング規約を決めていなかったり、あいまいにしたまま進めていくと、書式が統一されていないため、コードを追加すればするほどゴチャゴチャしたコードになりがちです。チームでコーディングしていくならなおさら。今回チー…bookmarks: 382category: テクノロジーノンデザイナーこそ押さえておきたい!グッとくるWebサイト配色パターン集 | Find Job ! Startup配色・カラーデザインに悩んだ経験、ありますよね! 今回のエントリでは色別に、Webサイトの配色サンプルをまとめました。 以前のエントリで取り上げた通り、ベースカラー:70%、メインカラー:25%、アクセントカラー:5%という配色のルールにのっとりご紹介していきます。 エンジニア・ディレクターも知っておいて損はさせません。もちろん本職デザイナーの方々にも役立つ、怒濤の配色大事典です! 【黄】楽観的・…bookmarks: 373category: 暮らし@nifty:デイリーポータルZ:接待のこと教えてください久しぶりにあった同級生が居酒屋で箸をもう一つ頼んでとりわけはじめた。なんだその技は。 どうやら彼は製薬会社の営業職として8年間接待しまくってきてそこで身につけたのだという。 いいかげんに生きてきた筆者は接待なんてしたこともなければされたこともなく。接待というものを一度やってみたくなった。bookmarks: 203category: 世の中山口・萩 高校生のLINE情報で避難 NHKニュース28日の大雨で川が氾濫し、多くの被害が出た山口県萩市では、地元の高校生たちが「LINE」と呼ばれるインターネット上のサービスを使って避難を呼びかけるなどして、地域の人たちの避難に役立てていたことが分かりました。 山口県萩市須佐に住む高校1年生の中村悠里さん(15)は、28日午前10時半ごろ、LINEを使った友人とのやり取りで、自宅の前を流れる須佐川が氾濫しそうなことを知りました。 悠里さんは、母親…bookmarks: 213category: エンタメ「マジンガーZ」まさかの美少女アニメ化 | 東スポWeb – 東京スポーツ新聞社2013年07月30日 (火) 新聞購読・バックナンバーについて | サイトマップ 文字サイズ 小島慶子が突然ツイートをすべて削除 トップ > エンタメ > アニメ > 「マジンガーZ」まさかの美少女アニメ化 人気ランキング フジ加藤アナ「パン子」の真相 松井のライバル・マルティネス氏「彼との勝負は楽しかった」 松井氏「今日プレーするんだろう?ってジーターが」 確かだったフジ本田アナの「男を選ぶ目…bookmarks: 73category: アニメとゲーム見えない部分のパンツを作り込むフィギュアメーカーの技術力の無駄遣いを現役パッケージデザイナーが解説 – GIGAZINE7月28日にワンダーフェスティバル 2013[夏]が開催されました。プロ・アマ問わず、並大抵ではない作り込みやこだわりを持った品が展示されていましたが、女の子のフィギュアは普通に立っていると見えないスカートの中のパンツまで造型されていることが多々あります。これは作り手側のこだわりが反映されたものですが、一体、なぜこんな見えない部分にまで力が注がれるようになったのか。フリーライターの廣田恵介さんが、…bookmarks: 123category: テクノロジーNEC:スマホ事業撤退へ 「ツートップ」外され状況悪化- 毎日jp(毎日新聞)NECがスマートフォン(多機能携帯電話)事業から撤退する方針を固めたことが30日、分かった。中国レノボと携帯電話事業の統合を目指して交渉していたが、出資比率などが折り合わずに統合を見送ることになり、単独での収益改善は見込めないと判断した。一方で従来型の携帯電話は一定の需要があるとみて事業を継続する。 NECの携帯電話事業は14年3月期に約150億円の営業赤字を見込んでおり、4年連続となる見通し。N…bookmarks: 57category: テクノロジーPhotoshopで文字をよりシャープにクリアに見せるこつ -1px未満のこだわり | コリスdribbbleに投稿されたデザインで、コメントのやり取りがちょっと興味深いものなので紹介します。 簡単に意訳すると、 ビジター「デザインきれいだな、文字周りの処理に秘訣とかあるの?」 オーナー「文字をクリアにみせるために、Photoshopでこういう風にやってるよ。」 という感じです。 Site テクニックの紹介の前に、まずは文字周りを実寸大にしたものから。 Site -実寸大画像 カラーのコン…bookmarks: 256category: 暮らしツイッター民、青春18切符を買う→使い方わからず1回使って捨てる→駅員に再発行しろとクレーム1 サッカーボールキック(東京都) :2013/07/30(火) 09:58:08.71 ID:2Ee2ohPHP ?PLT(12113) ポイント特典https://twitter.com/kazutt/status/360215963729272832 kazutt/カズ 2013/07/25(木) 10:52:33 via Twitter for iPhone 人生初!青春18切符。 620…bookmarks: 39category: 世の中「穴栗」「穴粟」…難読市「訂正」のお便り作戦 : 社会 : YOMIURI ONLINE(読売新聞)難読地名で知られる兵庫県宍粟(しそう)市が、「穴栗(あなぐり)」や「穴粟(あなあわ)」と誤記した郵便物の送り主に対し、やんわりと「訂正」のお便りを送り、PRにつなげる作戦に乗り出した。 観光パンフレットも同封し、便箋いっぱいに四季折々の自然あふれる市の魅力をアピール。中には、相手先からのお礼はがきも届いており、市の担当者は「奇策」に手応えを感じている。 市に寄せられる郵便物やメールには地名の誤記が…bookmarks: 80category: 政治と経済ナチスの手口学んだら…憲法改正で麻生氏講演 : 政治 : YOMIURI ONLINE(読売新聞)麻生副総理は29日、都内で開かれた講演会で憲法改正について、「狂騒、狂乱の中で決めてほしくない。落ち着いた世論の上に成し遂げるべきものだ」と述べた。 その上で、ドイツでかつて、最も民主的と言われたワイマール憲法下でヒトラー政権が誕生したことを挙げ、「ワイマール憲法もいつの間にかナチス憲法に変わっていた。あの手口を学んだらどうか。(国民が)騒がないで、納得して変わっている。喧騒(けんそう)の中で決め…bookmarks: 254category: 暮らし日本酒の歴史 昭和60年代以降 – 板前日記昭和40年代後半になると日本酒蔵では、「このまま三増酒だけではいけない」「売れればいいだけの桶売りでは日本酒の将来はない」「自分が美味しいと思うお酒を造りたい」という若い世代が出現し始めます。酒屋さんにも全国で「自分の売っているお酒は本当に美味しいのか?」「こんな不味い酒じゃなくどこかに美味しいお酒があるはずだ」と目覚める若い世代がポツポツと現れ始めます。 昭和50年代は蔵元も酒屋さんも、志のある…bookmarks: 158category: 世の中やや日刊カルト新聞: 下村文科相・猪瀬都知事らがワールドメイト教祖のイベントで挨拶=文科省・都など後援、首相も祝電2013年7月30日火曜日 下村文科相・猪瀬都知事らがワールドメイト教祖のイベントで挨拶=文科省・都など後援、首相も祝電 挨拶に立つ下村大臣。前列中央の赤ネクタイが半田氏、空席を挟んで左が猪瀬知事(下村大臣のブログより) 参院選のさなかの7月18・19日、都内で開催された「スポーツ平和サミット東京大会」を文部科学省と東京都が後援。猪瀬直樹・都知事と下村博文・文部科学大臣が出席して挨拶しましたが、大…bookmarks: 39category: エンタメお待ちかね! 「もつ鍋 わたり」のプロ野球前半戦「激辛総括」2013。(1/5) – Number Web : ナンバー中野渡氏も訪れた、いわきでのオールスター第3戦。注目の大谷翔平(中央)は8回に同点打を放つなど活躍し、スポンサーから新車をゲット。しかし免許はまだ取得していないという。 photograph by KYODO 2013年夏。 気温が上がったり下がったりで、猛暑なのか冷夏なのかはっきりしない今日この頃。そんなどっちつかずの夏には煮えたぎる鍋を喰らってのナイター観戦が恋しくもなります。 そんな気分にな…bookmarks: 68category: 学び幸福の科学信者は異常でキリスト教信者は正常ってのはどういう理屈でそうなるわけ?キリストが石をパンに変えたり、水をワインに変えたりすんのも、大川隆法総裁が公開霊言すんのも、おなじようなもんじゃんツイートするbookmarks: 150category: テクノロジーJavaでIDEのアクセッサ生成よりlombokを使ったほうがいい理由 – きしだのはてなlombokは、JavaでのアクセッサやtoString、equalsなどボイラープレートなコードをコンパイル時に生成してくれるライブラリです。ただ、こういったコードの生成は、IDEを使えば自動で行えるので、わざわざlombokを導入するまでもないと考えることもできますが、ぼくはlombokを導入するべきだと考えて、lombokを使うようにしました。このとき「lombokを導入するべき」と考えた理…bookmarks: 50category: 世の中米上院「尖閣」で中国非難の決議 NHKニュースアメリカ議会上院は29日、中国当局が沖縄県の尖閣諸島の周辺に船を派遣して地域の緊張を高めていると非難したうえ、中国側に自制を求める決議を全会一致で採択しました。 この決議はアメリカ議会上院の外交委員会に所属する与野党の議員が提出したもので、上院は29日の本会議で、全会一致で採択しました。 決議は沖縄県の尖閣諸島を含む東シナ海や南シナ海で中国の海洋当局が活動を活発化させていると指摘したうえ、「中国の…bookmarks: 40 […]

  3. Guest より:

    昨日渡しもコーディングガイドラインに関するエントリーを執筆致しました。
    http://junmaruyama.info/codingguideline/

  4. Jun Maruyama より:

    先日私もコーディングガイドラインに関するエントリーを執筆致しました。
    http://junmaruyama.info/codingguideline/

  5. […] コーディング規約を作ろう | Webクリエイターボックス […]

ニュースレター

Web制作の最新情報やWebクリエイターボックスからのお知らせ、中の人の近況等を定期的にお送りいたします。 ぜひご登録ください!もちろん無料です! :)