- 이번 포스트의 내용을 정리하면 다음과 같습니다.
- 잘 달린 주석은 그 어떤 정보보다 유용하다.
- 주석이 필요한 상황에 처하면 곰곰이 생각해보자.
→ 상황을 역전해 코드로 의도를 표현할 방법은 없을까?- 주석은 오래될수록 코드에서 멀어진다. (평생 유지 보수는 현실적으로 불가능)
- 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.
- 복구성 없는 주석 (헛갈리게 만드는 주석)
- 관련성 없는 주석 (잘못 위치한 주석)
- 정확성 없는 주석 (잘못된 정보를 적어둔 주석)
주석이 없는 것이 가장 최선!
꼭 적어야 한다면 맥락과 기능을 이해하기 쉽게 작성해두는 것이 좋다고 생각합니다.
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags && HOURLY_FLAG) && (employee.age > 65))
if (employee.isEligibleForFullBenefits ())
개인적인 생각은 좋은 주석 보다는 유효(용)한 주석이 아닌가 싶습니다.
법적인 주석
회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라 명시하는 경우
// Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.
// GNU General Public License 버전 2 이상을 따르는 조건으로 배포한다.
// 모든 조항, 조건을 열거하는 대신 표준 라이선스나 외부 문서를 참조해도 됨
정보를 제공하는 주석
기본적인 정보를 주석으로 제공하면 편리
// 테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderinstance();
// 위 함수의 이름을 responderBeingTested(); 로 바꾸면 주석이 필요 없어진다.
// hh:mm:ss AM/PM, MM dd, yyyy 형식이다.
// 11:52:59 AM, May 18, 2021
Pattern timeMatcher = Pattern.compile(
"\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");
// 시각과 날짜를 변환하는 클래스를 만들어 코드를 옮겨주면 더 좋고 깔끔할 것임.
의도를 설명하는 주석
때로는 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명
public int compareTo(Object o) {
if(o instanceof WikiPagePath) {
WikiPagePath p = (WikiPagePath) o;
String compressedName = StringUtil.join(names, "");
String compressedArgumentName = StringUtil.join(p. names, "");
return compressedName.compareTo(compressedArgumentName);
}
return 1; // 오른쪽 유형이므로 정렬 순위가 더 높다.
}
public void testConcurrentAddWidgets() throws Exception {
Widget Builder widgetBuilder =
new WidgetBuilder(new Class[]{BoldWidget.class});
String text = "'''bold text'''";
ParentWidget parent =
new BoldWidget(new MockWidgetRoot(), "'''bold text'''";
AtomicBoolean failFlag = new AtomicBoolean();
failFlag.set(false);
// 스레드를 통한 widget 생성으로 어떻게든 경쟁 조건을 만들려 시도한다.
for (int i = 0; i < 25000; i++) {
WidgetBuilderThread widgetBuilderThread =
new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
Thread thread = new Thread(widgetBuilderThread);
thread.start();
}
assertEquals(false, failFlag.get());
}
의미를 명료하게 밝히는 주석
public void testCompareTo() throws Exception {
WikiPagePath a = PathParser.parse("PageA");
WikiPagePath b = PathParser.parse("PageB");
WikiPagePath aa = PathParser.parse("PageA.PageA");
WikiPagePath bb = PathParser.parse("PageB.PageB");
WikiPagePath ba = PathParser.parse("PageB.PageA");
assertTrue(a.compareTo(a) == 0); // a = a
assertTrue(a.compareTo(b) != 0); // a != b
assertTrue(ab.compareTo(ab) == 0); // ab = ab
assertTrue(a.compareTo(b) == -1); // a < b
assertTrue(aa.compareTo(ab) == -1); // aa < ab
assertTrue(ba.compareTo(bb) == -1); // ba < bb
assertTrue(b.compareTo(a) == 1); // b > a
assertTrue(ab.compareTo(aa) == 1); // ab > aa
assertTrue(bb.compareTo(ba) == 1); // bb > ba
}
결과를 경고하는 주석
// 여유 시간이 충분하지 않다연 실횅하지 마십시오.
public void _testWithReallyBigFile() {
writeLinesToFile(10000000);
response.setBody(testFile);
response.readyToSend(this);
String responsestring = output.toString();
assertSubString("Content-Length: 1000000000", responsestring);
assertTrue(bytesSent > 1000000000);
@Ignore("실행이 너무 오래 걸린다.")
_
기호를 붙이는 방법이 일반적인 관례public static SimpleDateFormat makeStandardHttpDateFormat() {
// SimpleDateFormat은 스레드에 안전하지 못하다.
// 따라서 각 인스턴스에 독립적으로 생성해야 한다.
SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy")
df.setTimeZone (TimeZone.getTimeZone ("GMT"));
return df;
}
TODO 주석
//TODO
주석으로 남겨두면 편하다.// TOOO-IMM 현재 필요하지 않다.
// 세크아웃 모델을 도입하면 함수가 필요 없다.
protected Versioninfo makeVersion() throws Exception {
return null;
}
중요성을 강조하는 주석
String listItemContent = match.group(3).trim();
// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.
new ListItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.end()));
공개 API에서의 Javadocs
주절거리는 주석
public void loadProperties() {
try {
String properties Path = propertiesLocation + "/" + PROPERTIES_FILE;
FileInputStream propertiesStream = new FileInputStream(propertiesPath);
loadedProperties.load(propertiesStream);
} catch(IOException e) {
// 속성 파일이 었다면 기본간을 모두 메모리로 읽어 들였다는 의미다.
}
}
같은 이야기를 중복하는 주석
// waitForClose
// this.closed가 true일 때 반환되는 유릴리티 메서드다.
// 타임아웃에 도달하면 예외믈 던진다.
public synchronized void waitForClose(final long timeoutMillis) throws Exception {
if(!closed) {
wait(timeoutMillis);
if(!closed) throw new Exception("MockResponseSender could not be closed");
}
}
오해할 여지가 있는 주석
의무적으로 다는 주석
모든 함수에 javadocs를 달거나 모든 변수에 주석을 달라는 규칙은 어리석기 그지 없다!
아무런 가치가 없는 주석의 예
/**
*
* @param title CD 제목
* @param author CD 저자
* @param tracks CD 트랙 숫자
* @param durationInMinutes CD 길이(단위: 분)
*/
public void addCD(String title, String author, int tracks, int durationlnMinutes) {
CD cd = new CD();
cd.title = title;
cd.author = author;
cd.tracks = tracks;
cd.duration = durationInMinutes;
cdList.add(cd);
}
이력을 기록하는 주석
있으나 마나 한 주석
너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석
/**
* 기본 생성자 */
protected AnnuaIDateRule() { }
/** 월 중 일자 */
private int dayOfMonth;
// 전형적인 중복
/**
* 월 중 일자를 반환한다.
*
* @return 월 중 일자
*/
public int getDayOfMonth() { return dayOfMonth;}
// 첫 catch 주석은 적절해보이지만 다음 catch의 주석은 분풀이일 뿐..
private void startSending() {
try {
doSending();
} catch (SocketException e) {
// 정상, 누군가 요청을 멈춤.
} catch (Exception e) {
try {
response.add(ErrorResponder.makeExceptionString(e));
response.closeAll();
} catch (Exception e1) {
// 이게 뭐지?
}
}
}
지나친 참견이 되므로 이러한 주석을 본 개발자가 주석을 무시하는 습관에 빠진다.
코드가 바뀌면서 주석은 거짓말로 변한다.
있으나 마나 한 주석을 달 시간에 코드를 정리하자.
의미 없는 javadocs도 잡음이다. (문서를 제공해야 한다는 잘못된 욕심으로 탄생한 잡음.)
함수나 변수로 표현할 수 있다면 주석을 달지 말 것
// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) {
}
// 이 코드에서 주석을 없애고 다시 표현하면 다음과 같다.
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) {
}
위치를 표시하는 주석
소스 파일에서 특정 위치를 표시하려 주석을 사용하는 케이스
// actions ////////////////////////////////////
가끔씩 사용하는 배너는 눈에 띄며 주의를 환기한다
그러나, 배너를 남용하면 독자가 흔한 잡음으로 여기며 무시한다.
닫는 괄호에 다는 주석
public class wc {
public static void main(String[] args) {
BufferedReader in = new BufferedReader(new InputStreamReader(System.in));
String line;
int lineCount = 0;
int charCount = 0;
int wordCount = 0;
try {
while ((line = in.readLineO) != null) {
lineCount++;
charCount += line.length();
String words[] = line.split("WW");
wordCount += words.length;
} //while
System.out.println("wordCount = " + wordCount);
System.out.println("lineCount = " + lineCount);
System.out.println("charCount = " + charCount);
} //try
catch (IOException e) {
System.err.println("Error:1" + e.getMessage());
} //catch
} //main
}
공로를 돌리거나 저자를 표시하는 주석
주석으로 처리한 코드
HTML 주석
/**
* 적합성 테스트 * 수행하기 위한 과업
* 이 과업은 적합성 테스트 * 수행해 결과> 추력한다.
* <p/>
* <pre>
* 용법:
* <taskdef name="execute-fitnesse-tests"
* classname="fitnesse.ant.ExecuteFitnesseTestsTask"
* classpathref="classpath" />
* 뜨는
* <taskdef classpathref="classpath"
* resource=" tasks. properties" />
* <p/>
* &U; execute-f itnesse-tests
* suitepage=" FitNesse. SuiteAcceptanceTes t s"
* fitnesseport="8082"
* resultsdir느"${ results. dir}"
* result shtnlpag은=&qu°t; fit-results, html"
* classpath ref="classpath" />
* </pre>
*/
전역 정보
/**
* 적합성 테스트가 동작하는 포트: 기본값은 <b>8082</b>.
*
* @param fitnessePort
*/
public void setFitnessePort(int fitnessePort)
{
this.fitnessePort = fitnessePort;
}
너무 많은 정보
// RFC 번호를 제외하면 독자에게 불필요하며 불가사의한 정보일 뿐이다.
/*
RFC 2045 - Multipurpose Internet Mail Extensions (MIME)
1부: 인터넷 메시지 본체 형식
6.8절. Base64 내용 전송 인코딩(Content-Transfer-Encoding)
인코딩 과정은 입력 비트 중 24비트 그룹을 인코딩된 4글자로 구성된
출력 문자열로 표현한다. 왼쪽에서 오른쪽으로 진행해가며, 3개를 묶어 8비트 입력
그룸을 형성한다. 이렇게 만들어진 24비트는 4개를 묶어 6비트 그룹으로 취급하며,
각각은 base64 알파벳에서 단일 자릿수로 해석된다.
base64 인코딩으로 비트 스트림을 인코딩할 때, 비트 스트림은
MSB(Most Significant Bit) 우선으로 정렬되어 있다고 가정한다. 따라서, 스트림에서
첫 번째 비트는 첫 8비트 바이트에서 최상위 비트가 되며, 여덟번째 비트는 첫 8비트 바이트에서 최하위 비트가 된다.
*/
모호한 관계
// 필터 바이트란 무엇인가?
// +1과 관련있는 것인가?
// 한 픽셀이 한 바이트인가?
/*
* 모든 픽셀을 담을 만큼 충분한 배열로 시작한다(여기에 필터 바이트를 더한다).
* 그리고 헤더 정보를 위해 200바이트롤 더한다.
*/
this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];
함수 헤더
비공개 코드에서 Javadocs
해당 코드는 책 저자의 주관에 따라 리팩토링 된 코드이므로 참고용으로 보는 것이 바람직할 것 같습니다. (확실한 정답이 아님!)
/**
* 이 클래스는 사용자가 지정한 최대 값까지 소수를 생성한다. 사용된 알고리즘은
* 에라스토테네스의 채다.
* <p>
* 에라스토테네스: 기원전 276년에 리비아 키레네에서 출생, 기원전 194년에 사망
* 자구 둘레를 최초로 겨개산한 사람이자 달력에 윤년을 도입한 사람.
* 알륵산드리아 도서관장을 역임.
* <p>
* 알고리즘은 상당히 단순하다. 2에서 시작하는 정수 배열을 대상으로
* 2의 배수를 모두 제거한다. 다음으로 남은 정수를 찾아 이 정수의 배수를 모두 지운다.
* 최대 값의 제곱근이 될 때까지 이를 반복한다.
*
* @author Alphonse
* @version 13 Feb 2002 atp
*/
import java.util.*;
public class GeneratePrimes {
/**
* @param maxValue는 소수를 찾아낼 최대 값
*/
public static int[] generatePrimes(int maxValue) {
if (maxValue >= 2) // 유일하게 유효한 경우
{
// 선언
int s = maxValue + 1; // 배열 크기
boolean[] f = new boolean[s];
int i;
// 배열을 참으로 초기화
for (i = 0; i < s; i++)
f[i] = true;
// 소수가 아닌 알려진 숫자를 제거
f[0] = f[1] = false;
// 체
int j;
for (i = 2; i < Math.sqrt(s) + 1; i++) {
if (f[i]) // i가 남아 있는 숫자라면 이 숫자의 배수를 구한다.
{
for (j = 2 * i; j < s; j += i)
f[j] = false; // 배수는 소수가 아니다.
}
}
// 소수 개수는?
int count = 0;
for (i = 0; i < s; i++) {
if (f[i])
count++; // 카운트 증가
}
int[] primes = new int[count];
// 소수를 결과 배열로 이동한다.
for (i = 0, j = 0; i < s; i++) {
if (f[i]) //소수일 경우에
primes[j++] = i;
}
return primes; // 소수를 반환한다.
}
else // maxValue < 2
return new int[0]; // 입력이 잘못되면 비어 있는 배열을 반환한다.
}
}
/**
* 이 클래스는 사용자가 지정한 최대 값까지 소수를 구한다
* 알고리즘은 에라스토테네스의 체다.
* 2에서 시작하는 정수 배열을 대상으로 작업한다.
* 처음으로 남아 있는 정수를 찾아 배수를 모두 제거한다.
* 배열에 더 이상 배수가 없을 때까지 반복한다.
*/
public class PrimeGenerator {
private static boolean[] crossedOut;
private static int[] result;
public static int[] generatePrimes(int maxValue) {
if (maxValue < 2)
return new int[0];
else {
uncrossIntegersUpTo(maxValue);
crossOutMultiples();
putUncrossedIntegersIntoResult();
return result;
}
}
private static void uncrossIntegersUpTo(int maxValue) {
crossedOut = new boolean[maxValue + 1];
for (int i = 2; i < crossedOut.length; i++)
crossedOut[i] = false;
}
private static void crossOutMultiples() {
int limit = determineIterationLimit();
for (int i = 2; i <= limit; i++) {
if (notCrossed(i))
crossOutMultiplesOf(i);
}
}
private static int determineIterationLimit() {
// 배열에 있는 모든 배수는 배열 크기의 제곱근보다 작은 소수의 인수다.
// 따라서 이 제곱근보다 더 큰 숫자의 배수는 제거할 필요가 없다.
double iterationLimit = Math.sqrt(crossedOut.length);
return (int) iterationLimit;
}
private static void crossOutMultiplesOf(int i) {
for (int multiple = 2 * i; multiple < crossedOut.length; multiple += i) {
crossedOut[multiple] = true;
}
}
private static boolean notCrossed(int i) {
return crossedOut[i] == false;
}
private static void putUncrossedIntegersIntoResult() {
result = new int[numberOfUncrossedIntegers()];
for (int j = 0, i = 2; i < crossedOut.length ; i++) {
if (notCrossed(i))
result[j++] = i;
}
}
private static int numberOfUncrossedIntegers() {
int count = 0;
for (int i = 2; i < crossedOut.length; i++)
if (notCrossed(i))
count++;
return count;
}
}