TIL (Today I Learned)
2022.02.24
오늘 읽은 범위
4장. 주석
책에서 기억하고 싶은 내용을 써보세요.
-
주석은 '순수하게 선하지' 못하다. 사실상 주석은 기껏해야 필요악이다. (p.68)
-
우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다. (p.68)
-
자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라! (p.69)
-
좋은 주석들 (가장 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이다!) (p70 ~ 75)
-
법적인 주석
-
정보를 제공하는 주석
-
의도를 설명하는 주석
-
의미를 명료하게 밝히는 주석
-
결과를 경고하는 주석
// 여유 시간이 충분하지 않다면 실행하지 마십시오.
public void _testWithReallyBigFile() {
writeLinesToFile(10000000);
response.setBody(testFile);
response.readyToSend(this);
String responseString = output.toString();
assertSubString("Content-Length: 1000000000", responseString); assertTrue(bytesSent > 1000000000);
}-
TODO 주석
-
중요성을 강조하는 주석
String listItemContent = match.group(3).trim();
// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.
new ListItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.end()));- 나쁜 주석 (대다수 주석이 이 범주에 속한다.) (p.75 ~
- 주절거리는 주석
public void loadProperties() {
try {
String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;
FileInputStream propertiesStream = new FileInputStream(propertiesPath);
loadedProperties.load(propertiesStream);
}
catch(IOException e)
{
// 속성 파일이 없다면 기본값을 모두 메모리로 읽어 들였다는 의미다.
}
}위의 catch문 안에 있는 주석은 너무 모호해서 읽는 사람이 알아볼 수가 없다.
- 같은 이야기를 중복하는 주석
// 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를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다.
-
이력을 기록하는 주석
-
있으나 마나 한 주석
/**
* 기본 생성자
*/
protected AnnualDateRule() { }- 무서운 잡음
/** The name. */
private String name;
/** The version. */
private String version;
/** The licenceName. */
private String licenceName;
/** The version. */
private String info;-
함수나 변수로 표현할 수 있다면 주석을 달지 마라
-
위치를 표시하는 주석
-
닫는 괄호에 다는 주석
(Flutter의 방식이 아니던가!)
-
공로를 돌리거나 저자를 표시하는 주석
-
주석으로 처리한 코드
-
HTML 주석
-
전역 정보
-
너무 많은 정보
-
모호한 관계
-
함수 헤더
짦은 함수는 긴 설명이 필요 없다. 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.
오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요
이번 장은 정말로 충격적인 장이였다. 처음 코딩을 시작할 때 주석으로 설명을 달아 두는 것이 좋다고 작성한 코드에 주석을 다는 일을 계속해서 하라는 충고를 받은 적이 있었다. (물론 귀찮아서 안 한 지 오래다.) 하지만 저자는 주석이 꼭 필요한가를 지적한다. 주석을 관리하는데 시간을 쏟을 바에야. 알아보기 쉬운 코드를 만드는데 시간을 쏟으라고 말하면서 다음과 같은 예시를 보여준다.
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags && HOURLY_FLAG) && (employee.age > 65))if (employee.isEligibleForFullBenefits())정말 충격적 이게도 위의 방식이 이때까지 내가 해오던 방식이었고 밑의 방식은 생각조차 하지 못했다. 오늘은 정말로 내가 이때까지 코드를 짜오 던 방식에 대해 다시 한번 생각해보게 되었고 앞으로 어떤 방식으로 코드를 고쳐 나가야 할지 조금 감이 잡힌 날이었던 것 같다.
