Clean Comment | Formatting

Comment 란?

 

Code에 대한 사람이 읽을 수 있는 부가 설명.

사람이 Code를 더 쉽게 이해할 수 있게 하는 것이 목적이다.

 

 

▶ Clean Commet 원칙
  1. Comment는 필요악이다
  2. Comment는 대부분의 상황에서 사용하지 말아야 한다.
     (그러나 Comment를 사용해야 하는 몇 가지 예외 상황이 있다)

 

 

* 왜 최대한 코멘트를 피해야할까?

 

 >> Comment 보다 Code 그 자체가 의미 있어야 한다.

   - Comment로 부가 설명이 필요하다면 Code가 충분히 의미 있지 못하다는 것이다.

   - Comment에 의지하기 보다 의미있는 Code를 작성하는 노력이 필요하다

 

 >> Comment는 최신 정보를 담지 못한다.

   - Code를 변경한다고 Comment 변경도 필수가 아니기 때문에 항상 최신 정보로 수정하지 않는다. 따라서 Comment의 정보는 잘못 된, 오래 된 정보를 담고 있을 가능성이 높다.

 

 >> Comment는 불필요하고 중복된 정보를 포함하고 있을 수 있다.

   - Code로 의미를 충분히 표현하고 있는 경우, Comment의 중복적인 정보는 필요없게 된다.

   - 코드의 수정 이력을 표현하는 Comment는 형상 관리 도구로 충분히 정보를 담을 수 있다

 

 

Bad Comment의 유형

 

1. 의미가 모호한 코드를 설명하는 Comment

   : Code 자체로 충분히 명확한 표현이 안될 때 사용한다.

    → 가독성 향상을 목적으로 Comment를 작성하나 이럴때는 Code 자체를 개선해야 한다.

 

2. 중복된 정보를 나타내거나 의무적으로 작성하는 Comment

   : 의미가 분명한 Code에 Comment로 중복 설명을 한다.

    → Code 변경 시 Comment는 변경되지 않을 가능성도 존재한다. 따라서 이럴때는 중복을 제거해야 한다.

Comment가 없어도 Code는 자신의 역할을 하고있으므로 Comment의 존재이유가 없음

 

3. Comment 처리 된 Code

   : 당장 필요는 없지만 없애기는 아까운 Code들

    → 이는 Git과 같은 형상 관리 도구로 얼마든지 관리가 가능하다. 따라서 Comment 처리 된 Code는 무조건 삭제한다.

 

4. 이력을 남겨놓은 Comment

   : 특정 File이나 Class, Method에 수정 이력을 남겨 놓은 것

    → 이런 것도 Git과 같은 형상 관리 도구로 모든 이력이 관리된다. 따라서 모든 이력 Comment는 무조건 삭제한다.

 

 

 

따라서 Clean Comment 란, "Comment를 사용하지 않는 것"이다.

 

그러나 경우에 따라 코멘트가 필요한 예외 상황이 있다. 이럴때는 적절한 Comment 사용이 필요하다.

 

  1. 저작권 등을 명시하는 Comment

    →  회사 정책에 의해 소유권, 저작권 등을 표시해야 하는 경우가 있다. 이럴때는 모든 소스파일에 저작권 표시 Comment가 필요하다.

 

  2. 다수가 사용하는 Open API의 문서화

    → 오픈소스 라이브러리는 API 사용의 용이성을 높이기 우히ㅐ Java Doc과 같은 Comment가 필요하다.

 

  3. 이름만으로 충분히 의미를 전달하기 어려운 경우

    → 불가피하게 이름만으로 충분한 의미/의도를 표현하지 못하는 경우가 있다. 

        대표적인 사례로 복잡한 정규표현식의 의도 표현이 있다.

 

  4. TO DO Comment

    → TO DO Comment로 앞으로 해야 할 작업을 간략히 표시는 가능하다.

TO DO Comment를 인식해서 잊을 가능성이 적다

 

 

---

 

Code Formatting

코드의 가독성과 이해도를 높여주는 일련의 작업

 

Code Formatting은 수직적 Formatting 원칙과 수평적 Formatting 원칙으로 분류된다.

 

 

Formatting은 중요하다. Formatting이 동작에 영향을 미치지 않는다고 해서 무시해서는 안된다.

대부분 언어 별 Style Guide에는 Formatting이 반드시 포함되어 있을만큼, 가독성과 Foramatting은 밀접한 관련이 있다.

Formatting만 변경되어도 코드의 가독성은 향상된다.

관련되어있는 요소끼리 그룹화만 하더라도 가독성은 급격히 향상된다.

 

 

---

 

수직적 Formatting
코드의 위 → 아래로 진행된 흐름과 관련된 코드 작성 규칙

 → 코드 라인 간의 간격, 밀접한 관계를 가지는 코드 간의 그룹화 등이 포함된다.

 

≫ 추상화의 수준 순서로 코드를 배치한다.

 

≫ 서로 다른 개념은 분리한다.

  → 빈 행을 사용하여 글의 문단을 나누듯 코드의 개념을 분리한다.

 

≫ 유사한 개념은 모아 놓는다.

  → 개념적으로 유사한 내용은 빈 행을 사용하지 말고 붙여서 작성한다.

 

≫ 관계있는 내용은 가까운 행에 작성한다.

  → 코드를 읽기 위해 여러번의 Jump 하는 것을 방지하려면 관련있는 메소드들을 가까이 배치해야한다.

  → Method를 추가할 때는 시간적 순서가 아닌 논리적인 관련성에 따라 배치해야 한다.

 

 

 

수평적(Horizontal) Formatting
코드 한 줄에 대해 왼쪽 → 오른쪽으로 진행된 흐름과 관련된 코드 작성 규칙

 → 들여쓰기, 코드 간의 간격, 코드 행의 넓이 등이 포함된다.

 → 코드 한 줄을 스크롤의 이동없이 코드를 읽는 것을 목표로 한다.

 

≫ 들여쓰기를 적극적으로 활용한다.

  → 들여쓰기는 관련있는 개념들을 논리적인 그룹으로 묶어 가독성을 향상 시킨다. (일부 언어는 들여쓰기가 필수적임)

 

≫ 한 줄의 긴 코드를 여러 줄의 짧은 코드로 분리한다.

  → 수평 스크롤링 없이 코드를 읽고 이해할 수 있어야 한다.

 

≫ 수평 정렬은 중요하지 않다.

  → 수평 정렬은 해도 상관 없으니 필요하지는 않다. 오히려 이후 수정 시 추가 작업을 필요로할 가능성이 높다.

 

 

---

 

코드프레소 Java 웹 개발 체험단 활동 중 'SW 유지보수성 향상을 위한 Clean Code' 이러닝 강의를 듣고 작성하였습니다 :)
코드프레소 URL: https://www.codepresso.kr/

프리미엄 IT 교육 서비스 - 코드프레소