レビュー時に「読みやすいな」と思うHTML・CSS

## これは何

個人的にコードレビューにはいるときに読みやすいなと感じるコードの特徴をまとめてみました。

## レビュー時に「読みやすいな」と思うコードの特徴

### 不要なマークアップがない

本来なくても良いマークアップがあると、構造がその分複雑になるためコードを読みづらくなることが多いです。
また、不要なマークアップは減らした方がパフォーマンス的にも良いです。

:::note warn
ただし、「見た目」を表現する上では不要なマークアップでも情報の構造上は必要なマークアップは残すべきです。
:::

```html:不要なマークアップがある例
<section css={sectionStyle}>
  <div css={innerStyle}>
    <h2 css={titleStyle}>素敵なタイトル</h2>
    <p css={textStyle}><span>hogehoge</span></p>
  </div>
</section>
```

```html:不要なDOMを削除した例
<section css={sectionStyle}>
  <h2 css={titleStyle}>素敵なタイトル</h2>
  <p css={textStyle}>hogehoge</p>
</section>
```

### セマンティックなマークアップになっている

マークアップがきちんと意味を持っていると、タグをさらうだけで構造を把握できるので、コードを読みやすくなります。

:::note
HTMLのマークアップで使うh1~h6やpといった要素はそれぞれ「見出し」や「段落」といった意味を持ちます。
この意味を適切にマークアップすることを「セマンティックなマークアップ」と表現しています。
:::

また、セマンティックなマークアップを心がけると、前項の「不要なマークアップがない」状態を自然に作ることができます。

```html:セマンティックなマークアップになっていない例
<div css={sectionStyle}>
  <div>hogeのリスト</div>
  <div css={listStyle}>
    <span css={listItemStyle}>hogehoge1</span>
    <span css={listItemStyle}>hogehoge2</span>
    <span css={listItemStyle}>hogehoge3</span>
  </div>
  <div>hogehoge</div>
</div>
```

```html:セマンティックなマークアップになっている例
<section css={sectionStyle}>
  <h2>hogeのリスト</h2>
  <ol css={listStyle}>
    <li css={listItemStyle}>hogehoge1</li>
    <li css={listItemStyle}>hogehoge2</li>
    <li css={listItemStyle}>hogehoge3</li>
  </ol>
</section>
```

### マークアップとCSSの指定順が揃っている

マークアップとCSSの指定順が揃っていると、マークアップやデザインデータと照らし合わせて読みやすくなります。
CSSだけを読んでも大体どこの指定か予想できるのでいちいちマークアップと照らし合わせなくても良くなります。

また、CSSには「継承」という概念があり、一部のプロパティは親要素の指定を引き継いで反映します。
そのため、マークアップと指定順が揃っていると「どのスタイルが継承されるのか」が分かりやすくなります。

```html:DOM構造と指定順が揃っていない例（HTML）
<section css={sectionStyle}>
  <h2>hogeのリスト</h2>
  <ol css={listStyle}>
    <li css={listItemStyle}>hogehoge1</li>
    <li css={listItemStyle}>hogehoge2</li>
    <li css={listItemStyle}>hogehoge3</li>
  </ol>
</section>
```

```css:DOM構造と指定順が揃っていない例（CSS）
.listStyle {
  padding: 16px;
  list-style: none;
}

.listItemStyle {
  padding: 16px;
}

.sectionStyle {
  color: gray;
  padding: 16px;
}
```

```html:DOM構造と指定順が揃っている例（HTML）
<section css={sectionStyle}>
  <h2>hogeのリスト</h2>
  <ol css={listStyle}>
    <li css={listItemStyle}>hogehoge1</li>
    <li css={listItemStyle}>hogehoge2</li>
    <li css={listItemStyle}>hogehoge3</li>
  </ol>
</section>
```

```css:DOM構造と指定順が揃っている例（CSS）
.sectionStyle{
  color: gray;
  padding: 16px;
}

.listStyle{
  list-style: none;
  padding: 16px;
}

.listItemStyle{
  padding: 16px;
}
```

### プロパティの指定順にルールがある

CSSのプロパティの指定されている順序にルールがないと、どんなスタイルが指定されているかの把握に時間がかかります。
特にファイルが大きくなってくると、全体で指定順が揃っている時のコードが読みやすさがグッと上がります。

プロパティの種類（ボックスモデル、配置、色..）で並べ替えると、指定内容が分かりやすくなります。
メンテナンスコストが低くルールとして統一しやすいので、アルファベット順で並べる方法もおすすめです。

```css:指定順にルールがない例
.sectionStyle {
  color: gray;
  margin-top: 8px;
  height: 40px;
  padding: 16px;
  background: lightgray;
  width: 40px;
}

.listStyle {
  margin-top: 8px;
  color: gray;
  background: lightgray;
}
```

```css:指定順にルールがある例①プロパティの種類順
.sectionStyle {
  /* 色 */
  background: lightgray;
  color: gray;

  /* サイズ・余白 */
  width: 40px;
  height: 40px;
  margin-top: 8px;
  padding: 16px;
}

.listStyle {
  /* 色 */
  background: lightgray;
  color: gray;

  /* サイズ・余白 */
  margin-top: 8px;
}
```

```css:指定順にルールがある例②アルファベット順
.sectionStyle {
  background: lightgray;
  color: gray;
  height: 40px;
  margin-top: 8px;
  padding: 16px;
  width: 40px;
}

.listStyle {
  background: lightgray;
  color: gray;
  marginTop: 8px;
}
```

### クラス名からどの要素か推定しやすい

基本的に自分はまずマークアップを上からチェックし、次にCSSを上からチェックします。

スタイルはマークアップがセマンティックである状態でレビューしたいため、そもそも先にマークアップが適切かをチェックしたいからです。
また、マークアップとCSSを照らし合わせながらよりも視線移動が少なくスムーズに済みます。

そのため、CSSを読むときにマークアップと照らし合わせなくても「どのマークアップの部分か」が分かるとスムーズにコードが読めます。

```html:クラス名からどの要素か推定しにくい例（HTML）
<section css={wrapperStyle}>
  <h2>hogeのリスト</h2>
  <ol css={containerStyle}>
    <li css={itemStyle}>hogehoge1</li>
    <li css={itemStyle}>hogehoge2</li>
    <li css={itemStyle}>hogehoge3</li>
  </ol>
</section>
```

```css:クラス名からどの要素か推定しにくい例（CSS）
.wrapperStyle {
  padding: 16px;
}

.containerStyle {
  padding: 16px;
}

.itemStyle {
  padding: 16px;
}
```

```html:クラス名からどの要素か推定しやすい例（HTML）
<section css={sectionStyle}>
  <h2>hogeのリスト</h2>
  <ol css={listStyle}>
    <li css={listItemStyle}>hogehoge1</li>
    <li css={listItemStyle}>hogehoge2</li>
    <li css={listItemStyle}>hogehoge3</li>
  </ol>
</section>
```

```css:クラス名からどの要素か推定しやすい例（CSS）
.sectionStyle {
  padding: 16px;
}

.listStyle {
  padding: 16px;
}

.listItemStyle {
  padding: 16px;
}
```

### 不要な指定がされていない

不要な指定を減らすとコードがスッキリして読みやすくなります。
指定を省略するには以下のような方法があります

- :bulb: **継承を利用して指定を減らす**
    - `color`, `font-family`, `font-size`などの継承プロパティは、親要素に1度指定すれば、子要素にいちいち指定する必要がなくなります
- :bulb: **ショートハンドを活用する**
    - `margin`や`paddin`、`border`や`font`などはショートハンドを使ってプロパティをまとめて指定できます
- :bulb: **デフォルト値や`reset.css`と重複している指定を削除する**
    - プロパティごとの初期値や、`reset.css`・親要素から継承している値と重複して指定している場合は削除できます

:::note warn
コードを読みやすくするためにあえて省略せず指定する場合もあるので、無理に全てを省略する必要はありません。
:::

```html:不要な指定がされている例
<section css={sectionStyle}>
  <h2 css={titleStyle}>hogeのリスト</h2>
  <ul css={innerStyle}>
    <li css={listItemStyle}>hogehoge1</li>
    <li css={listItemStyle}>hogehoge2</li>
    <li css={listItemStyle}>hogehoge3</li>
  </ul>
</section>
```

```css:不要な指定がされている例
.sectionStyle {
  padding-top: 16px;
  padding-right: 24px;
  padding-bottom: 24px;
  padding-left: 16px;
}

.titleStyle {
  color: #333;
}

.listStyle {
  margin-right: 16px;
  margin-right: 16px;
  list-style-type: disc;
}

.listItemStyle {
  color: #333;
  border-color: gray;
  border-width: 1px;
  border-style: solid;
}
```

```html:不要な指定を削除した例
<section css={sectionStyle}>
  <h2>hogeのリスト</h2>
  <ul css={listStyle}>
    <li>hogehoge1</li>
    <li>hogehoge2</li>
    <li>hogehoge3</li>
  </ul>
</section>
```

```css:不要な指定を削除した例
.sectionStyle {
  color: #333; /* 継承を活用する */
  padding: 16px 24px; /* ショートハンドを活用する */
  /* デフォルト値を省略 */
}

.listStyle {
  margin-inline: 16px; /* ショートハンドを活用する */
  border: 1px solid gray; /* 同じプロパティをまとめる */
}
```

## 終わりに

コードが読みやすくなるとレビュー時に助かるだけでなく、開発時のミスを防いだりメンテナンス性が上がったりします。
もし他にも効果的なポイントやチームで取り組んでいるおすすめの方法などありましたら是非教えてください！