코딩 컨벤션이란? 🤔
읽고, 관리하기 쉬운 코드를 작성하기 위한 일종의 코딩 스타일 규약
린터를 사용한다는 가정하에 린터로 검출할 수 없는 모호한 부분을 가이드
이번에 회사에서 마크업 코딩 컨벤션 관련해서 정리하게 될 기회가 생겼습니다.
여러 포스팅들을 찾아보고 저희한테 맞는 코딩 컨벤션을 작성하기 위해서 자료를 정리해봤는데요.
회사에서는 웹앱으로 서비스가 제공되고 있어서 보편적인 웹서비스에 적용할 수 있는 마크업 코딩 컨벤션보다는 내용이 적습니다.
추가적으로 CSS에 대한 코딩 컨벤션은 작성하지 않았고, Naming Rule 에는 파스칼 케이스, 카멜 케이스, 케밥 케이스, 스네이크 케이스 등 다양한 케이스에 대한 내용을 작성하지는 않았습니다.
스네이크 케이스로 작성하기로 결정된 상태여서 스네이크 케이스를 기준으로 작성합니다.
🧑💻 마크업 컨벤션의 필요성
마크업 개발은 디자인, 브라우저, 스크립트, 성능, 접근성 등과 긴밀한 관계가 있습니다.
또한, 유지보수에 투자되는 비용을 최소화하기 위해 통일된 코드 작성법을 제시합니다.
개발을 하면서 코드를 최초로 작성한 사람이 끝까지 유지보수할 확률은 매우 낮습니다.
따라서, 최초 개발자가 아닌 사람도 코드를 빠르고 정확하게 이해할 수 있도록 작성하는 것은 코드의 유지보수 비용을 절감하고 업무 효율을 높이는데 결정적인 역할을 합니다.
어떤 코딩 컨벤션을 선택하는 것이 중요한 것이 아니라, 통일된 기준으로 소스 코드를 작성하는 것이 중요합니다.
📚 용어 정리
컨벤션에 자주 사용되는 용어의 정의를 설명합니다.
엘리먼트 (Element)
HTML 문서를 구성하는 요소(태그)를 의미합니다.
애트리뷰트 (Attribute)
엘리먼트에 부여할 수 있는 특성을 의미합니다.
선택자 (Selector)
엘리먼트를 식별할 수 있는 이름을 의미합니다.
요소에 CSS 스타일을 적용하기 위한 패턴입니다.
컴포넌트 (Component)
하나 이상의 기능 또는 역할을 가진 컨텐츠 단위의 UI 구성 요소를 의미합니다.
Syntax
- 들여쓰기는 2개의 공백 문자(소프트탭)을 사용합니다.
- 모든 엘리먼트 명과 애트리뷰트 명은 스네이크 표기법(
Snake Case)로 작성합니다. - 모든 애트리뷰트 값은 큰 따옴표(
"")를 사용합니다. - 닫는 태그가 선택적이어도 생략하지 않습니다. (ex:
</li>,</body>) - 빈 줄은 1줄을 초과하지 않습니다.
EditorConfig사용을 권장합니다.
EditorConfig
환경(Editor, OS, file encoding)에 따라 코딩 스타일의 일관성이 깨지는 문제를 해결하기 위한 표준
character encoding, 개행 처리 방법, 들여쓰기 방법(tab or space) 등을 정의
Doctype
HTML5 DTD(Document Type Definition)로 선언합니다.
추가적으로 자기 마침 태그 (Self-Closing Tags)에 후행 슬래시(/)를 사용하지 않습니다.
<!-- Bad -->
<input />
<br />
<!-- Good -->
<input>
<br>Naming Rule
- 이름은 영문 소문자, 숫자, 언더스코어(
_)로 작성합니다. - 시작 이름은 영문 소문자로만 시작할 수 있습니다.
- 언더스코어는 단어와 단어를 조합할 때만 사용합니다.
- 언더스코어가 포함된 약속어는 숫자, 영문 소문자와 조합하여 사용할 수 있습니다.
| 기본형 | 잘못된 예 | 올바른 예 |
|---|---|---|
| section | sectionList | section_list |
id, class Naming Rule
id는 문서 전체의 고유 식별자 이므로 한 문서에서 동일한id를 여러 번 사용하지 않습니다.- 레이아웃을 제외한
id는 스타일을 지정하지 않습니다. class는 문서에서 여러 번 사용할 수 있습니다.
HTML 코드 작성 규칙
W3C Validation
- HTML은 DTD의 명세에 맞게 작성하며, W3C Validation을 통과해야 합니다.
- DTD를 제외한 모든 엘리먼트와 애트리뷰트는 소문자로 작성합니다.
<!-- Bad -->
<SPAN Class="desc">간단한 설명</SPAN>
<!-- Good -->
<span class="desc">간단한 설명</span>HTML 애트리뷰트 작성 규칙
기본 규칙
- 엘리먼트에서
class,style을 선언할 때는 선언 순서를 준수합니다. class,style을 선언할 때는 제일 뒷부분에 선언합니다.- 애트리뷰트의 순서가 비슷한 엘리먼트끼리 통일되므로 검색하기 편해집니다.
<!-- Good -->
<input type="text" id="user_id" title="사용자" class="input_txt" style="width:100px">선언 순서
type=src>id=title=name>class>style
Boolean 애트리뷰트
- HTML5에서는
Boolean애트리뷰트를 선언하는 것만으로도true값을 가집니다. - 필요하지 않다면
Boolean값을 작성하지 않습니다.
<!-- Not Bad -->
<button disabled="true"></button>
<!-- Good -->
<button disabled></button>name 애트리뷰트
name애트리뷰트 값은 비즈니스 로직을 작성하는 언어의 Naming Rule에 맞게 작성하는 것을 권장합니다.- 저희는
Snake Case를 사용하고 있기 때문에 동일한 Naming Rule을 사용하면 됩니다.
<!-- Snake Case -->
<form class="form" id="my_form" name="my_form">
<input class="input" type="text" id="my_user_name" name="my_user_name">
</form>HTML 엘리먼트 작성 규칙
<input>
label요소,title애트리뷰트,alt애트리뷰트를 통해 스크린 리더 사용자는 주변 맥락에 대한 이해 없이 각 요소에 독립적으로 접근해도 폼을 이해할 수 있습니다.
type이 text인 경우
- 동일한 스타일의 텍스트 필드나 너비 값이 다를 경우
style애트리뷰트를 이용해서width값을 제어합니다. - 이렇게 하면 불필요한 클래스 생성을 막을 수 있습니다.
<!-- Bad -->
<input type="text" class="input input--width-120">
<input type="text" class="input input--width-180">
<!-- Good -->
<input type="text" class="input" style="width:120px">
<input type="text" class="input" style="width:180px">type이 radio, checkbox인 경우
- 그룹핑이 필요하면 선택적으로
name애트리뷰트를 이용하여 항목들을 그룹핑합니다.
type이 image인 경우
alt애트리뷰트를 반드시 선언합니다.
<label>
<input>,<select>,<textarea>와 같은 폼 요소는for애트리뷰트를 부여하여 해당 요소의id값과 동일한 이름으로 연결(coupling)합니다.- 단 레이블 명이 위치할 공간이 없는 경우
title애트리뷰트로 대체할 수 있습니다. <label>안에<input>엘리먼트가 있는 경우에는for와id를 이용하여 연결하지 않아도 됩니다.
<!-- for, id를 이용한 커플링 -->
<input type="radio" name="alignment" id="align_left">
<label for="align_left">왼쪽 정렬</label>
<!-- <label>안에 <input> 엘리먼트가 있는 경우 -->
<label><input type="checkbox" name="sports">축구</label><img>
src,width,height,title,alt,usemap애트리뷰트를 선택적으로 선언합니다.src,alt애트리뷰트에import한 이름과 동일한 값을 표기합니다.- 이미지를 볼 수 없는 환경(스크린 리더, 이미지 서버 장애, 이미지를 표시하지 않음 설정)에서도 내용을 확인할 수 있게 합니다.
title애트리뷰트를 선언한 경우에도alt애트리뷰트를 함께 선언합니다.title애트리뷰트는 브라우저에서 독립적으로 툴팁을 표현하기 위해서 사용합니다.
<!-- import, src, alt 애트리뷰트 -->
import FinanceBanner from '../../banner01.jpg'
<img src={FinanceBanner} alt="FinanceBanner">
<!-- 애트리뷰트 사용 예시 -->
<img src={FinanceBanner} width="30" height="10" title="배너" alt="배너" usemap="#help">NHN 코딩 컨벤션이나 다른 코딩 컨벤션을 확인해보면 더욱 자세한 컨벤션 내용을 확인할 수 있습니다. 🔎
누군가 이 내용을 봤을 때 컨벤션으로 많이 부족하다고 생각할 수 있습니다.
해당 내용을 다 적용하면 좋지만, 어떤 코딩 컨벤션을 선택하는 것이 중요한 게 아니라 우리에게 필요한 통일된 기준이 필요했습니다.
그러한 기준으로 봤을 때 현재 작성된 내용은 개인적으로 만족스럽습니다
혹시나 코딩 컨벤션을 정해야 하는 상황이라면 현재 가지고 있는 익숙함에 필요한 컨벤션을 추가하면서 코딩 컨벤션을 만들어가면 좋을 것 같습니다. 💪
