4. 주석

잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.

우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다.

주석은 나쁜 코드를 보완하지 못한다.

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다. 표현력이 풍부하고 깔끔하며 주석이 거의 없는코드가 복잡하고 어수선하며 주석이 많은 코드보다 훨씬 좋다.

코드로 의도를 표현하라

코드만으로 의도를 설명하기 어려운 경우가 존재한다. 하지만 대다수의 의도는 코드로 표현할 수 있다. 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

좋은 주석

필요하거나 유용한 주석도 있다. 하지만 정말 좋은 주석은 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을 명심하자.

• 법적인 주석
  • 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시하는 경우가 있다.
  • 예: 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보
• 정보를 제공하는 주석
  • 때로는 기본적인 정보를 주석으로 제공하면 편리하다.
  • 하지만 가능하다면 함수 이름에 정보를 담는 편이 더 좋다.
• 의도를 설명하는 주석
  • 구현을 이해하게 도와주는 것을 넘어 결정에 깔린 의도까지 설명하는 주석
• 의미를 명료하게 밝히는 주석
  • 모호한 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다.
  • 가능하다면 인수나 반환값 자체를 명확하게 만들면 좋겠지만, 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 주석이 유용하다.
  • 물론 그릇된 주석을 달아놓을 위험이 높아진다. 그러므로 주석을 달기 전 더 나은 방법이 없는지 고민하고 정확히 주석을 달도록 주의한다.
• 결과를 경고하는 주석
  • 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다.
• TODO 주석
  • TODO 주석에 프로그래머가 필요하다 여기짐나 당장 구현하기 어려운 업무를 기술한다.
  • 예: 더 이상 필요 없는 기능을 삭제하라는 알림, 누군가에게 문제를 봐달라는 요청, 더 좋은 이름을 떠올려달라는 부탁 등
  • 하지만 어떤 용도로 사용하는 시스템에 나쁜 코드를 남겨 놓는 핑계가 되면 안 된다.
  • 주기적으로 TODO 주석을 점검 및 정리하는 것이 좋다.
• 중요성을 강조하는 주석
  • 자칫 대수롭지 않다고 여겨질 무언가의 중요성을 강조하기 위해 사용한다.
• 공개 API에서 Javadocs

나쁜 주석

• 주절거리는 주석
  • 특별한 이유 없이 다는 주석
  • 주석을 달기로 했다면 충분한 시간을 들여서 최고의 주석을 달도록 노력하자.
  • 이해가 안 되어 달느 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석이다.
• 같은 이야기를 중복하는 주석
  • 코드 내용을 그대로 중복한 코드
• 오해할 여지가 있는 주석
  • 의도는 좋았으나 딱 맞을 정도로 엄밀하게 주석을 달지 못하기도 한다.
• 의무적으로 다는 주석
  • 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 하는 규칙은 코드를 복잡하게 만들며, 잘못된 정보를 제공할 여지를 만든다.
• 이력을 기록하는 주석
  • 모듈을 편집할 때마다 모듈 첫머리에 주석을 기록하는 것은 혼란만 가중한다.
• 있으나 마나 한 주석
  • 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석
• 무서운 잡음
  • 때로는 Javadocs도 잡음이다.
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표시하는 주석

  • 프로그래머가 소스 파일에서 특정 위치를 표시하려 주석을 사용할 때가 있다.

    // Actions ////////////////

  • 위와 같은 배너 아래 특정 기능을 모아놓으면 유용할 때도 있다.

  • 하지만 이런 주석은 가독성을 낮추기 때문에 제거하는 것이 좋다.

  • 이런 배너는 반드시 필요할 때만 가끔 사용하는 게 좋다.

• 닫는 괄호에 다는 주석
  • 닫는 괄호에 다는 특수한 주석은 중첩이 심하고 장황한 함수에선 의미가 있을 수도 있지만 작고 캡슐화된 함수에는 잡음일 뿐이다.
  • 닫는 괄호에 주석을 다는 것보단 함수를 줄이려고 시도해보자.
• 공로를 돌리거나 저자를 표시하는 주석
  • 이런 정보는 소스 코드 관리 시스템에 저장하는 편이 좋다.
• 주석으로 처리한 코드
  • 소스 코드 관리 시스템이 우리를 대신해 코드를 기억해준다. 그냥 코드를 삭제하자.
• HTML 주석
  • HTML 주석은 편집기/IDE에서조차 읽기 어렵다.
• 전역 정보
  • 주석을 달아야 한다면 근처에 있는 코드만 기술하라.
  • 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하면 안 된다.
• 너무 많은 정보
  • 주석에 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 마라.
• 모호한 관계
  • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.
• 함수 헤더
  • 짧고 한 가지만 수행하며 일믕르 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.
• 비공개 코드에서 Javadocs
  • 공개하지 않을 코드라면 Javadocs는 쓸모가 없다.

5. 형식 맞추기

프로그래머라면 형식을 깔끔하게 맞춰 코드를 짜야 한다. 코드 형식을 맞추기 위한 간단한 규칙을 정하고 그 규칙을 착실히 따라야 한다. 팀으로 일한다면 팀이 합의해 규칙을 정하고 모두가 그 규칙을 따라야 한다. 필요하다면 규칙을 자동으로 적용하는 도구를 활용한다.

형식을 맞추는 목적

코드 형식은 의사소통의 일환이고, 의사소통은 전문 개발자의 일차적인 의무다.

오늘 구현한 기능이 다음 버전에서 바뀔 확률은 아주 높다. 그런데 오늘 구현한 코드의 가독성은 앞으로 바뀔 코드의 품질에 지대한 영향을 미친다. 오랜 시간이 지나 원래 코드의 흔적을 더 이상 찾아보기 어려울 정도로 코드가 바뀌어도 맨 처음 잡아놓은 구현 스타일과 가독성 수준은 유지보수 용이성과 확장성에 계속 영향을 미친다. 원래 코드는 사라질지라도 개발자의 스타일과 규율은 사라지지 않는다.

그렇다면 원활한 소통을 위한 코드 형식은 무엇일까?

적절한 행 길이를 유지하라.

500줄을 넘지 않고 대부분 200줄 정도인 파일로도 커다란 시스템을 구축할 수 있다. 반드시 지켜야 하는 규칙은 아니지만 바람직한 규칙으로 삼자. 일반적으로 큰 파일보다 작은 파일이 이해하기 쉽다.

신문 기사처럼 작성하라

좋은 신문 기사를 떠올려보자. 독자는 위에서 아래로 기사를 읽는다. 최상단에는 기사를 요약하는 표제가 나온다. 첫 문단은 전체 기사 내용을 요약한다. 쭉 읽으며 내려가면 세세한 사실이 조금씩 드러난다.

소스 파일도 이와 비슷하다. 이름은 간단하면서도 설명이 가능하게 짓는다. 소스 파일 첫 부분은 고차원 개념과 알고리즘을 설명한다. 아래로 내려갈수록 의도를 상세히 묘사한다. 마지막에는 가장 저차원 함수와 세부 내역이 나온다.

개념은 빈 행으로 분리하라

코드의 각 행은 수식이나 절을 나타내고, 일련의 행 묶음은 완결된 생각 하나를 표현한다. 생각 사이는 빈 행을 넣어 분리해야 한다.

세로 밀집도

줄바꿈이 개념을 분리한다면 세로 밀집도는 연관성을 의미한다. 즉, 서로 밀접한 코드 행은 세로로 가까이 놓여야 한다.

수직 거리

서로 밀접한 개념은 세로로 가까이 두어야 한다. 타당한 근거가 없다면 서로 밀접한 개념은 한 파일에 속해야 하고, 그래서 protected 변수를 피해야 한다.

연관성이 깊은 두 개념이 멀리 떨어져 있으면 코드를 읽는 사람이 소스 파일과 클래스를 여기저기 뒤져봐야 한다.

• 변수 선언
  • 변수는 사용하는 위치에 최대한 가까이 선언한다.
• 인스턴스 변수
  • 반면 인스턴스 변수는 클래스 맨 처음에 선언하고, 변수 간에 세로로 거리를 두지 않는다.
    • 대다수의 클래스 메서드가 인스턴스 변수를 사용하기 때문이다.
  • 인스턴스 변수를 선언하는 위치는 아직도 논쟁이 분분하다. 중요한 것은 잘 알려진 위치에 인스턴스 변수를 모아야 한다는 것이다.
• 종속 함수
  • 한 함수가 다른 함수를 호출한다면 두 함수는 세로로 가까이 배치한다.
  • 가능하면 호출하는 함수를 호출되는 함수보다 먼저 배치한다.
• 개념적 유사성
  • 개념적인 친화도가 높을수록 코드를 가까이 배치한다.
  • 친화도가 높은 요인은?🤔
    • 한 함수가 다른 함수를 호출하는 경우 (직접적인 종속성)
    • 변수와 그 변수를 사용하는 함수
    • 비슷한 동작을 수행하는 함수 (예: assertTrue(), assertFalse())

세로 순서

일반적으로 함수 호출 종속성은 아래 방향으로 유지한다. 따라서 호출되는 함수는 함수를 호출하는 함수보다 나중에 배치해야 한다. 그러면 소스 코드 모듈이 자연스럽게 고차원에서 저차원으로 내려간다.

가로 형식 맞추기

프로그래머는 명백히 짧은 행을 선호한다. 80자~120자 사이가 제일 이상적이다.

가로 공백과 밀집도

가로로는 공백을 사용해 밀접한 개념과 느슨한 개념을 표현한다.

• 할당문은 왼쪽과 오른쪽 요소가 분명히 나뉜다. 공백을 넣으면 두 요소가 확실히 나뉜다는 사실이 분명해진다.
• 함수 이름과 이어지는 괄호 사이에는 공백을 넣지 않는다.
  • 함수와 인수는 서로 밀접하기 때문이다.
  • 공백을 넣으면 한 개념이 아니라 별개로 보인다.
• 함수를 호출하는 코드에서 괄호 안 인수는 공백으로 분리한다.
• 연산자 우선순위를 강조하기 위해 공백을 사용한다.
  • 승수 사이에는 공백이 없다.
  • 항 사이에는 공백이 들어간다.
  • 다만 코드 형식을 자동으로 맞춰주는 도구는 대다수가 연산자 우선순위를 고려하지 못하기 때문에 공백을 넣어줘도 없어지는 경우가 흔하다.

가로 정렬

private    Socket         socket;
private    InputStream    input;

위처럼 선언부의 변수 이름이나 할당문의 오른쪽 피연산자를 빠뜨리지 않고 나란히 정렬하는 것은 유용하지 못하다. 코드가 엉뚱한 부분을 강조해 진짜 의도가 가려지기 때문이다.

선언문과 할당문을 별도로 정렬하지 않으면 오히려 중대한 결함을 찾기 쉽다.

정렬이 필요할 정도로 목록이 길다면 문제는 목록 길이지 정렬 부족이 아니다. (선언부가 길다면 클래스를 쪼개야 한다는 의미다.)

들여쓰기

소스 파일은 윤곽도(outline)와 계층이 비슷하다. 계층에서 각 수준은 이름을 선언하는 범위이자 선언문과 실행문을 해석하는 범위다.

범위로 이뤄진 계층을 표현하기 위해 우리는 코드를 들여쓴다. 들여쓰는 정도는 계층에서 코드가 자리잡은 수준에 비례한다.

들여쓰기 무시하기

간단한 if문, 짧은 while문, 짧은 함수에서 들여쓰기 규칙을 무시하는 것을 지양한다.

가짜 범위

빈 while문이나 for문은 가능한 피하자. 피하지 못할 때는 빈 블록을 올바르게 들여쓰고 괄호로 감싼다.

팀 규칙

프로그래머라면 각자 선호하는 규칙이 있다. 하지만 팀에 속한다면 자신이 선호해야 할 규칙은 바로 팀 규칙이다.

좋은 소프트웨어 시스템은 읽기 쉬운 문서로 이뤄진다는 사실을 기억하기 바란다.

6. 객체와 자료 구조

자료 추상화

// 1. 구체적인 Point 클래스
public class Point {
	public double x;
	public double y;
}
// 2. 추상적인 Point 클래스
public interface Point {
	double getX();
	double getY();
	void setCartesian(double x, double y);
	double getR();
	double getTheta();
	void setPolar(double r, double theta);
}

2번은 자료 구조 이상을 표현한다. 클래스 메서드가 접근 정책을 강제한다. 좌표를 읽을 때는 각 값을 개별적으로 읽어야 한다. 하지만 좌표를 설정할 때는 두 값을 한꺼번에 설정해야 한다.

반면 1번은 확실히 직교좌표계를 사용하고, 개별적으로 좌표값을 읽고 설정하게 강제한다. 또한 구현을 노출한다. 변수를 private으로 선언하더라도 각 값마다 조회(get) 함수와 설정(set) 함수를 제공한다면 구현을 외부로 노출하는 셈이다.

변수 사이에 함수라는 계층을 넣는다고 구현이 저절로 감춰지지 않는다. 구현을 감추려면 추상화가 필요하다. 추상 인터페이스를 제공해 사용자가 구현을 모른 채 자료의 핵심을 조작할 수 있어야 진정한 의미의 클래스다.

자료를 세세하게 공개하기보다는 추상적인 개념으로 표현하는 편이 좋다. 인터페이스나 조회/설정 함수만으로는 추상화가 이뤄지지 않는다. 개발자는 객체가 포함하는 자료를 표현할 가장 좋은 방법을 심각하게 고민해야 한다. 아무 생각 없이 조회/설정 함수를 추가하는 방법이 가장 나쁘다.

자료/객체 비대칭

객체는 추상화 뒤로 자료를 숨긴 채 자료를 다루는 함수만 공개한다. 자료 구조는 자료를 그대로 공개하며 별다른 함수는 제공하지 않는다.

자료 구조를 사용하는 절차적인 코드는 기존 자료 구조를 변경하지 않으면서 새 함수를 추가하기 쉽다. 반면, 객체 지향 코드는 기존 함수를 변경하지 않으면서 새 클래스를 추가하기 쉽다.

절차적인 코드는 새로운 자료 구조를 추가하기 어렵다. 그러려면 모든 함수를 고쳐야 한다. 객체 지향 코드는 새로운 함수를 추가하기 어렵다. 그러려면 모든 클래스를 고쳐야 한다.

디미터 법칙

디미터 법칙은 모듈은 자신이 조작하는 객체의 속사정을 몰라야 한다는 법칙이다. 다시 말해 “클래스 C의 메서드 f는 다음과 같은 객체의 메서드만 호출해야 한다"고 주장한다.

• 클래스 C
• f가 생성한 객체
• f 인수로 넘어온 객체
• C 인스턴스 변수에 저장된 객체

하지만 위 객체에서 허용된 메서드가 반환하는 객체의 메서드는 호출하면 안 된다.

기차 충돌

final String outputDir = ctxt.getOptions().getScratchDir().getAbsolutePath();

위와 같은 코드를 기차 충돌(train wreck)이라고 부른다. 여러 객차가 한 줄로 이어진 기차처럼 보이기 때문이다. 조잡하게 보이기 때문에 피하는 것이 좋다. 대신 아래와 같이 나누는 편이 좋다.

Options opts = ctxt.getOptions();
File scratchDir = getScratchDir();
final String outputDir = getAbsolutePath();

위 코드가 디미터 법칙을 위반하는지 여부는 ctxt , Options , ScratchDir 이 객체인지 자료 구조인지에 달렸다. 객체라면 내부 구조를 숨겨야 하므로 확실히 디미터 법칙을 위반한다. 반면 자료 구조라면 당연히 내부 구조를 노출하므로 디미터 법칙이 적용되지 않는다.

위는 조회 함수를 사용하는 바람에 혼란을 일으킨다. 아래와 같이 구현헀다면 디미터 법칙을 거론할 필요가 없다.

final String outputDir = ctxt.options.scratchDir.absolutePath;

잡종 구조

때떄로 절반은 객체, 절반은 자료 구조인 잡종 구조가 나온다. 잡종 구조는 다른 함수가 절차적인 프로그래밍의 자료 구조 접근 방식처럼 비공개 변수를 사용하고 싶도록 만든다.

이런 구조는 새로운 함수는 물론이고 새로운 자료 구조도 추가하기 어렵다. 그러므로 되도록 피하는 것이 좋다.

구조체 감추기

만약 ctxt , Options , ScratchDir 이 객체라면 앞에 있던 예제처럼 줄줄이 엮으면 안 된다. 객체라면 내부 구조를 감춰야 하기 때문이다.

그렇다면 임시 디렉토리의 절대 경로는 어떻게 얻어야 할까?

// 1.
ctxt.getAbsolutePathOfScratchDirectoryOption();
// 2.
ctxt.getScratchDirectoryOption().getAbsolutePath();

첫 번째 방법은 ctxt 객체에 공개해야 하는 메서드가 너무 많다. 두 번째 방법은 getScratchDirectoryOption() 이 객체가 아닌 자료 구조를 반환한다고 가정해도 썩 내키지 않는다.

ctxt 가 객체라면 뭔가를 하라고 말해야지 속을 드러내라고 말하면 안 된다. 위 코드에서 임시 디렉토리의 절대 경로가 필요한 이유는 임시 파일을 생성하기 위한 목적이다.

BufferedOutputStream bos = ctxt.createScratchFileStream(classFileName);

그렇다면 ctxt 객체에 임시 파일을 생성하라고 시키면 디미터 법칙을 위반하지 않을 수 있다. ctxt 는 내부 구조를 드러내지 않으며, 모듈에서 해당 함수는 자신이 몰라야 하는 어떤 객체를 탐색할 필요가 없기 때문이다.

자료 전달 객체

자료 구조체의 전형적인 형태는 공개 변수만 있고 함수가 없는 클래스다. 이런 자료 구조체를 때로는 자료 전달 객체(Data Transfer Object, DTO)라 한다. DTO는 특히 데이터베이스와 통신하거나 소켓에서 받은 메시지의 구문을 분석할 때 유용하다.

좀 더 일반적인 형태는 bean 구조다. 빈은 private 변수를 조회/설정 함수로 조작한다. 이는 일종의 사이비 캡슐화로, 별다른 이익을 제공하지 않는다.

활성 레코드

활성 레코드는 DTO의 특수한 형태다. 대개 save나 find와 같은 탐색 함수도 제공한다. 활성 레코드는 데이터베이스 테이블이나 다른 소스에서 자료를 직접 변환한 결과다.

활성 레코드에 비즈니스 규칙 메서드를 추가해 객체로 취급하는 것은 바람직하지 않다. 잡종 구조가 나오게 되기 때문이다.

이를 해결하는 방법은 활성 레코드를 자료 구조로 취급하는 것이다. 비즈니스 규칙을 담으면서 내부 자료를 숨기는 객체는 따로 생성한다.

결론

어떤 시스템을 구현할 때, 새로운 자료 타입을 추가하는 유연성이 필요하면 객체가 더 적합하다. 다른 경우로 새로운 동작을 추가하는 유연성이 필요하면 자료 구조와 절차적인 코드가 더 적합하다. 우수한 소프트웨어 개발자는 편견 없이 이 사실으 ㄹ이해해 직면한 문제에 최적인 해결책을 선택한다.