주석

프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력만 있다면, 주석은 필요가 없다

좋은 주석

1. 법적인 주석

// Copyright (c) 2019, 2020, 2021 by Effort Guy, All rights reserved.
// GNU General Public License 버전 2 이상을 따르는 조건으로 배포한다.

2. 정보를 제공하는 주석

// kk:mm:ss EEE, MMM dd, yyyy 형식이다.
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");

3. 의도를 설명하는 주석

// 스레드를 대량으로 생성하는 방법으로, 어떻게든 경쟁 조건을 만드려고 시도한다.
for (int i = 0; i < 25000; i++){
	WidgetBuilderThread widgetBuilderThread = 
    	new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
   	Thread thread = new Thread(widgetBuilderThread);
    thread.start();
 }

4. 결과를 경고하는 주석

// 평균 10분 정도 걸리는 작업입니다.
public void calcBalance()...

5. IDE에서 인식할 수 있는 주석 - Todo Fixme

// Todo, Fixme 주석을 달아 놓으면 IDE에서 해당 주석만 몰아서 볼 수 있다.
// Todo 로그를 추가해야 함
private Order getOrder()...
 
// Fixme 간헐적으로 디코딩 에러가 발생함
private Student getStudent()...

6. 중요성을 강조하는 주석

// 문자열 시작 시 공백이 있으면, 다른 문자열로 인식되기 때문에 trim() 은 정말 중요하다.
String listItemContent = match.group(3).trim()

나쁜 주석

• 자신만 알아듣게 주절거리는 주석
• 코드와 동일한 내용을 써놓는 주석 - 코드 읽는게 더 빠르다
• 애매한 정보가 있는 주석 - 오해하기 쉽게
• 의무적으로 다는 주석 - 모든 메소드의 인자를 의미없이 의무적으로 다는 주석 (찔린다..)

부정확하고 코드로 확실히 표현할 수 있는 주석은 필요없다

마치며

나도 개발을 할때 컨트롤러에 어떤 http method인지 파라미터는 뭔지 리턴값은 뭔지를 달았다..
주석을 달때는 자바와 백엔드에 익숙하지 않은 프론트엔드 개발자분도 이해하기 쉽게 적었는데 이미 코드에 의미가 다 내포되어있는 상황에서 의무적으로 달지는 않았나 반성한다..