4장 주석
불가피하게 주석을 달아야 하는 경우에 주석을 작성하는 방법을 알려주는 챕터
나쁜 코드에 주석을 달지말고 새로 짜라.
주석은 코드의 의도를 표현함에 있어서 실패함을 의미한다.
변화하고 진화하는 코드에 주석은 따라가지 못한다.
목차
- 주석은 나쁜 코드를 보완하지 못한다
- 코드로 의도를 표현하라!
- 좋은 주석
- 법적인 주석
- 정보를 제공하는 주석
- 의도를 설명하는 주석
- 의미를 명료하게 밝히는 주석
- 결과를 경고하는 주석
- TODO 주석
- 중료성을 강조하는 주석
- 공개 API에서 Javadocs
- 나쁜 주석
- 주절거리는 주석
- 같은 이야기를 중복하는 주석
- 오해할 여지가 있는 주석
- 이력을 기록하는 주석
- 있으나 마나 한 주석
- 무서운 잡음
- 함수나 변수로 표현할 수 있다면 주석을 달지 마라
- 위치를 표시하는 주석
- 닫는 괄호에 다는 주석
- 공로를 돌리거나 저자를 표시하는 주석
- 주석으로 처리한 코드
- HTML 주석
- 전역 정보
- 너무 많은 정보
- 모호한 관계
- 함수 헤더
- 비공개 코드에서 Javadocs
- 예제
- 결론
1-1. 주석은 나쁜 코드를 보안하지 못한다
주석을 추가하는 일반적인 이유 : 코드의 품질이 나쁘기 때문에
주석을 달아야겠다 ✕
코드를 리팩토링해야 한다 ○
주석이 없고 표현력이 높은 코드를 작성하자.
1-2. 코드로 의도를 표현하라!
주석으로 의도를 표현하기 보다 설명을 함수로 만들어 표현해도 충분하다.
두번째 있는 조건문이 더 현명하게 의도를 코드에 반영한 예시라고 볼 수 있다.
// 나이가 65이하인 직원중에 복지 혜텍을 받을 자격 있는지 검사하는 조건문
if( (employee.flags & HOURLY_FLAG) && (employee.age > 65) )
if( employee.isEligibleForFullBenefits() )
1-3. 좋은 주석
주석은 필요악이지만 글자 값을 하는 주석 몇가지를 소개한다.
1-3-1. 법적인 주석
법적인 이유로 특정 주석을 넣으라고 명시하는 경우
// Copyright © 2018. All Rights Reserved. 이메일무단수집거부
// MIT License를 따르는 조건으로 배포한다.
1-3-2. 정보를 제공하는 주석
기본적인 정보( 추상화된 메서드가 반환하는 값 )를 주석으로 제공하면 편리하다.
// 테스트 중인 HttpResponse 인스턴스를 반환한다.
public abstract HttpResponse responseInstance();
public abstract HttpResponse responseBeingTested();
정규표현식 같은 경우에도 뜻하는 정규식을 표현하는 주석도 편리하다.
하지만 정규표현식으로 변환하는 함수 혹은 클래스를 만들어 코드로 옮겨주면 더 좋고 더 깔끔하겠다.
// @Condition 문자열이 있는 지 파악하는 정규식
const re = new RegExp('/\*[ \t]*@Condition')
const validator = (rawInput: string ): boolean => {
return rawInput.split(" ").includes('@Condition')
}
1-3-3. 의도를 설명하는 주석
개발자가 코드를 작성하면서 개발자의 의도가 바탕으로된 결정을 설명하는 주석
public int compareTo(Object obj){
if(obj instanceof PagePath){
return PagePath.getPath().compareTo(PagePath.getOriginPath());
}
return 1; // 다른 유형이므로 정렬 순위가 더 높다.
}
// 스레드를 대량 생산하는 방법으로 클라이언트의 무분별한 요청에 대한 테스트한다.
public void testRequest() throws Exception{
for(int idx = 0; idx < 50000; idx++){
RequestBuilder requestBuilder = new ReqestBuilder("URL", "GET", "JWT");
Thread thread = new Thread(new RequestThread(requestBuilder));
thread.start();
insertTestResult(idx);
}
}
1-3-4. 의미를 명료하게 밝히는 주석
때때로 모호한 인수나 반환값의 의미를 읽기 좋게 표현하면 읽는 사람이 이해하기 쉬워진다.
주석이 틀린 정보를 제공하는 위험이 있기 때문에 신중히 작성해야한다.
sort( (a, b) => { a - b } ) // 오름차순 정렬, 문자열의 경우 아스키 코드값을 비교
sort( (a, b) => { b - a } ) // 내림차순 정렬, 문자열의 경우 아스키 코드값을 비교
1-3-5. 결과를 경고하는 주석
다른 개발자에게 결과를 경고하는 목적으로 주석을 사용하는 경우이다.
// 개발용 DB가 아니라면 절대 실행하지 마십시오.
@Test
public void dropTable(){
...
String sql = "drop table user";
...
}
1-3-6. TODO 주석
앞으로 할 일이나 개발자가 필요하다 여기는 기능이지만 구현하지 않은 이유와 미래에 구현된 모습을 설명하는 주석이다.
// TODO-MdM 현재 필요하지 않다.
// 로딩 여부를 확인할 수 있다면 컴포넌트 랜더링 도중에 로딩이미지 혹은 애니메이션을 재생할 수 있다.
const isLoading = () => {
return null
}
1-3-7. 중요성을 강조하는 주석
읽는 사람이 대수롭지 않다고 여겨질 것같은 무언가에 중요성을 강조하기 위해서 사용한다.
const isLoading = useState(true)
// 여기서 초기값 true가 정말 중요하다.
// isLoading 상태값은 다음에 불러올 컴포넌트의 랜더링 여부를 판단한다.
1-4. 나쁜 주석
대부분의 주석이 나쁜 주석에 속한다.
대부분은 허술한 코드를 변명하거나 미숙한 결정을 합리화하는 프로그래머의 독백에서 크게 벗어나지 못한다.
1-4-1. 주절거리는 주석
특별한 이유없이 의무감 혹은 프로세스에서 지시한 경우 마지못해 주석을 다는 경우이다.
주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석으로 달도록 노력한다.
try{
...
}catch(err){
// 에러가 났다면 try 문에서 에러가 났다는 의미이다.
...
}finally{
// 에러가 발생해도 실행한다는 내용이다.
...
}
주절거리는 주석으로 읽는 사람에게 하여금 코드를 깊게 찾아봐야하는 주석은 제대로 소통하지 못하는 주석이다.
메모리만 낭비한다.
1-4-2. 같은 이야기를 중복하는 주석
읽을 코드 내용을 그대로 중복하는 주석
// 로그의 인덱스를 저장하는 변수
private String logSeq;
// 로그의 내용을 저장하는 변수
private String logContent;1-4-3. 오해할 여지가 있는 주석
실제 코드가 동작하는 것과 살짝 다른 정보를 설명하는 주석이 달려있는 경우
// 문자열 매개변수의 맨 마지막에 확장자가 없다면 확장자를 붙여주는 함수
const appendTxt = (rawInput: string) :string => {
let temp = rawInput
if( rawInput.split(".").indexOf(".wav") < 0 ){
temp += ".wav"
}
return rawInput;
}
1-4-4. 의무적으로 다는 주석
모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 하는 규칙은 잘못되었다.
아래 name 주석의 경우 저자의 이름인지 책의 이름인지 코드만 헷갈리게 만드는 주석이다.
/**
* @param name 이름
* @param chapter 챕터명
*/
public void addBook(String name, String chapter){}
1-4-5. 이력을 기록하는 주석
모듈에 변경을 기록하는 일지 혹은 일기로 사용하는 주석
형상관리 시스템이 없는 시절에는 유용했지만 지금은 혼란만 가중되는 주석이다.
/*
프로젝트 이력 (2021년 06월 부터)
-----------------------
2021년 06월 : 프로젝트 Init
2021년 07월 : 프로젝트 마무리
2021년 08월 : 프로젝트 배포
2021년 09월 : 프로젝트 디버깅 후 재배포
*/
1-4-6. 있으나 마나 한 주석
너무 당연한 사실을 주석으로 언급하며 새로운 정보를 제공하지 못하는 주석이다.
public Class UserDto(){
// 사용자의 나이를 저장하는 정수형 변수
private int age;
...
// 기본 생성자
protected UserDto(){}
...
}
1-4-7. 무서운 잡음
주석이 수행하는 목적이 없이 작성된 주석
//The address
private String address;
//The name
private String name;
//The Age
private int age;
1-4-8. 함수나 변수로 표현할 수 있다면 주석을 달지 마라
주석이 필요하지 않도록 코드를 개선하는 방법이다.
// 나이가 65이하인 직원중에 복지 혜텍을 받을 자격 있는지 검사하는 조건문
if( (employee.flags & HOURLY_FLAG) && (employee.age > 65) )
if( employee.isEligibleForFullBenefits() )
앞선 코드로 의미를 표현하라에서 설명한 내용과 같다.
주석이 필요하지 않도록 함수나 변수의 코드를 개선한다 .
1-4-9. 위치를 표시하는 주석
특정 위치를 표시하기 위한 주석을 사용하는 경우
// 여기 부터는 redux-saga로 비동기요청하는 공간
...
// 여기 부터는 컴포넌트를 리턴하는 공간
...
1-4-10. 닫는 괄호에 다는 주석
중첩이 심하고 장황한 함수라면 의미가 있지만
이 책에서 설명하는 작고 캡슐화된 함수에는 필요하지 않는 주석이다.
public static void main(String[] args){
try{
while(true){
...
} // while
}catch(Exception e){
...
}// catch
...
}// try
...
}// main
닫는 괄호에 주석을 달아야겠다는 생각이 든다면 함수를 줄이려 시도해보자.
1-4-11. 주석으로 처리한 코드
주석으로 처리한 코드는 이유가 있어서 남겨놨기 때문이거나 혹은 중요하니까
지우면 안된다고 생각하기 때문에 쓸모없는 코드임에도 지워지지 않을 때가 있다.
형상관리 시스템이 코드를 기억해주기 때문에 주석으로 처리할 필요없이 삭제하는 것이 좋다.
1-4-12. HTML 주석
주석중에 HTML 주석이 가장 혐오 그 자체이다.
해당 주석의 책임은 프로그매러가 아닌 편집기 도구가 짊어져야 한다.
/*
<div>
<h4 > < 안녕하세요 클린 코드입니다. > <h4 />
<hr />
<div />
*/
1-4-13. 전역 정보
주석을 달아야 한다면 근처에 있는 코드만 설명하라.
코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.
/*
DB Port : 8080
@param name 사용자 이름
*/
public Stirng setUserName(String userName){
this.userName = userName;
}
1-4-14. 너무 많은 정보
불필요하고 관련 없는 정보를 설명하는 주석
특정한 정보에 대한 역사같은 해당 역할에 있어서 필요하지 않은 주석
1-4-15. 모호한 관계
주석과 주석이 설명하는 대상 코드는 둘 사이의 관계가 명백해야 한다.
공들여 주석을 달았다면 적어도 읽는 사람이 주석과 코드를 보고 무슨 소린지 알아야 한다.
아파치 commons에서 가져온 주석이다.
/*
* 모든 픽셀을 담을 만큼 충분한 배열로 시작한다(여기에 필터 바이트를 더한다).
* 그리고 헤더 정보를 위해 200바이트를 더한다.
*/
this.pngBytes = new byte[ ((this.width + 1) * this.height * 3) + 200];
1-4-16. 함수 헤더
짧은 함수는 긴 설명이 필요없다.
길이가 짧고 한 가지 기능만 수행하여 이름을 잘 붙인 함수는 주석으로 설명한 함수보다 훨씬 좋다.
( 책에서는 주석으로 헤더를 추가한 함수보다 훨씬 좋다라고 나와있지만 번역이 잘 못 된거같다 )
1-4-17. 비공개 코드에서 Javadocs
공개 API는 Javadocs가 유용하지만 비공개 코드라면 Javadocs를 사용할 필요가 없다.
유용하지 않을 뿐만 아니라 Javadocs이 요구하는 형식 때문에 코드의 가독성만 떨어지고 산만해 진다.
결론
혼자 개발하고 혼자 요구사항에 맞추는 환경에서는 관계없는 챕터 일 수도 있지만
프로그래머는 소통할 수 있어야하고 소통의 도구 중 하나는 주석이 될 수도 있다.
혼자 개인의 입장에서 코드를 짜고 내가 읽고 이해하기 편한 방식으로 코드를 짜기보다는
같이 개발하는 사람 입장에서 또는 코드를 읽는 사람 입장에서 코드를 작성하는 것과
코드를 바라봐야 하는 시각이 중요하다는 걸 알 수 있는 챕터이다.
5장 형식 맞추기
'Etc > Clean Code[ Robert C. Martin ]' 카테고리의 다른 글
| [Clean Code] 6장 객체와 자료구조 (0) | 2022.04.10 |
|---|---|
| [Clean Code] 5장 형식 맞추기 (0) | 2022.04.07 |
| [Clean Code] 3장 함수 (0) | 2022.04.02 |
| [Clean Code] 2장 의미있는 이름 (0) | 2022.04.02 |
| [Clean Code] 1장 깨끗한 코드란?? (0) | 2022.04.02 |