[클린코드] 4~6장 정리(주석, 형식 맞추기, 객체와 자료 구조)

<클린코드> 책을 통해 공부한 내용을 정리하기 위해 작성하였습니다. 제 개인적인 각색과 의견이 첨가되어 있어 실제 책의 내용과는 차이가 있을 수 있습니다.

4장. 주석

- (내 생각) 코드는 영어를 기반으로 되어 있다. 영어를 유창하게 사용할 수 있는 사람들과 상대적으로 그러지 못한 사람들에게 다가오는 좋은 네이밍의 편안함은 정도가 다르다. 영어가 모국어가 아닌 나라들에서는 좀 더 주석에 관대해져야 하는 부분들이 있지 않을까 생각해본다. 간단한 영어 문장조차 해석하기 버거워하는 동료에게 "이정도는 정말 자세하게 잘 작성한 네이밍이니 공부해서라도 익숙해져주길 바래" 라고 일종의 무언의 압박을 주는 편이 맞는 걸까? 그렇다면 또 이러한 동료들을 위해 매 함수들마다 친절하게 모국어로 주석을 일일이 달아줘야 하는가? 물론 저자도 주석은 없으면 없을수록 좋다는 입장이지 절대 사용하지 말아라라는 입장은 아니다(거의 '절대 사용하지 말아라'의 입장인 것 같기도하다). 아무튼 모국어가 영어가 아닌 곳에서의 주석 작성은 고민의 여지가 더 많은 영역인 것 같다.

 

- 주석은 오래될수록 코드에서 멀어진다. 오래될수록 완전히 그릇될 가능성도 커진다. 이유는 단순하다. 프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능하니까.

 

- 때로 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다. 가령, 로컬테스트 시 해당 기능은 주석처리 하십시오 등의 주석이 되겠다.

 

- 공개 API를 구현한다면 반드시 훌륭한 Javadocs를 작성한다. 하지만 이 장에서 제시하는 나머지 충고도 명심하기 바란다. 여느 주석과 마찬가지로 Javadocs 역시 독자를 오도하거나, 잘못 위치하거나, 그릇된 정보를 전달할 가능성이 존재한다.

-> (내 생각) swagger 같이 내부 코드에 정리한 코드 스펙들이 외부 명세로도 보여지는 식의 라이브러리가 좋은 것 같다. 잘못된 주석이 큰 문제가 될 수 있는 부분중 하나는 내부 스펙 명세를 위한 주석에는 잘못된 정보를 적어놓고 외부로 노출되는 명세에는 올바른 정보를 적어 정보사이에 동기화가 안된 경우이다. 조기에 발견하면 그나마 다행이지만 시간이 지난 후 발견하게 된다면 히스토리를 파악하는 데 상당한 시간을 소요하게 될 수도 있다. 고로 차라리 동기화가 되어버리는 swagger같은 라이브러리가 좋은 것 같다.

 

- 특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 마지못해 주석을 단다면 전적으로 시간낭비다. 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.

 

- 이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석이다. 그런 주석은 바이트만 낭비할 뿐이다.

 

- 같은 이야기를 중복하는 주석은 코드상 충분히 이해가 가능한 로직인데 이를 굳이 말로 풀어서 작성해 놓은 주석을 의미한다. 이는 지양하는게 좋지 않을까? 엔진 후드를 열어볼 필요가 없다며 고객에게 아양 떠는 중고차 판매원과 비슷하다.

-> (내 생각) 설계가 잘못되고 코드의 품질이 떨어지는 레거시들의 경우엔 주석을 통해 이해를 도와주는 편이 좋겠다.

 

- 의무적으로 다는 주석은 지양하자. 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다. 이런 주석은 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래한다.

 

- 있으나 마나 한 주석은 뭘까? 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석이다.

 

- 함수나 변수로 표현할 수 있다면 주석을 달지 말아라

 

- 1960년대 즈음에는 주석으로 처리한 코드가 유용했었다(코드를 작성해놓고 일부러 주석처리를 해놓는 것을 의미하는 듯 하다). 하지만 우리는 오래전부터 우수한 소스 코드 관리 시스템을 사용해왔다. 소스 코드 관리 시스템이 우리를 대신해 코드를 기억해준다. 이제는 주석으로 처리할 필요가 없다. 그냥 코드를 삭제하라. 잃어버릴 염려는 없다. 약속한다.

5장. 형식 맞추기

- 뚜껑을 열었을 때 독자들이 코드가 깔끔하고, 일관적이며, 꼼꼼하다고 감탄하면 좋겠다. 질서 정연하다고 탄복하면 좋겠다. 모듈을 읽으며 두 눈이 휘둥그래 놀라면 좋겠다. 전문가가 짰다는 인상을 심어주면 좋겠다. 그 대신에 술 취한 뱃 사람 한 무리가 짜놓은 듯 어수선해 보인다면 독자들은 프로젝트의 다른 측면도 똑같이 무성의한 태도로 처리했으리라 생각할 것이다.

 

- 어쩌면 '돌아가는 코드'가 전문 개발자의 일차적인 의무라 여길지도 모르겠다. 하지만 이 책을 읽으면서 생각이 바뀌었기 바란다. 오늘 구현한 기능이 다음 버전에서 바뀔 확률은 아주 높다. 그런데 오늘 구현한 코드의 가독성은 앞으로 바뀔 코드의 품질에 지대한 영향을 미친다. 오랜 시간이 지나 원래 코드의 흔적을 더 이상 찾아보기 어려울 정도로 코드가 바뀌어도 맨 처음 잡아놓은 구현 스타일과 가독성 수준은 유지보수 용이성과 확장성에 계속 영향을 미친다. 원래 코드는 사라질지라도 개발자의 스타일과 규율은 사라지지 않는다.

-> (내 생각) 일단 정곡을 찔렸다. '돌아가는 코드'를 전문 개발자의 0순위 의무라고 생각해왔기 때문이다. 그럼에도 잊지말자. 기능이 요구사항에 맞게 동작하도록 만들 정도의 실력은 갖춰야한다..

 

- 신문 기사처럼 작성하라. 신문은 다양한 기사로 이뤄진다. 대다수 기사가 아주 짧다. 어떤 기사는 조금 길다. 한 면을 채우는 기사는 거의 없다. 신문이 읽을 만한 이유는 여기에 있다. 신문이 사실, 날짜, 이름 등을 무작위로 뒤섞은 긴 기사 하나만 싣는다면 아무도 읽지 않으리라.

 

- 개념은 빈 행으로 분리하라. 빈 행은 새로운 개념을 시작한다는 시각적 단서다. 코드를 읽어 내려가다 보면 빈 행 바로 다음 줄에 눈길이 멈춘다.

 

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

 

- 서로 밀접한 개념은 세로로 가까이 둬야 한다. 물론 두 개념이 서로 다른 파일에 속한다면 규칙이 통하지 않는다. 하지만 타당한 근거가 없다면 서로 밀접한 개념은 한 파일에 속해야 마땅하다. 이게 바로 protected 변수를 피해야 하는 이유 중 하나다.

 

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

 

- 변수는 사용하는 위치에 최대한 가까이 선언한다. 우리가 만든 또는 만들 함수는 매우 짧으므로 지역 변수는 각 함수 맨 처음에 선언한다.

-> (내 생각) 함수가 한 기능을 하고 매우 짧다는 전제! 아닐 경우엔 어쨌든 관련 로직과 최대한 가까이 선언한다.

 

- 반면, 인스턴스 변수는 클래스 맨 처음에 선언한다. 변수 간에 세로로 거리를 두지 않는다. 잘 설계한 클래스는 클래스의 많은(혹은 대다수) 메서드가 인스턴스 변수를 사용하기 때문이다.

 

- 한 함수가 다른 함수를 호출한다면 두 함수는 세로로 가까이 배치한다. 또한 가능하다면 호출하는 함수를 호출되는 함수보다 먼저 배치한다.

 

- 참고로, 아래 코드는 상수를 적절한 수준에 두는 좋은 예제다. getPageNameOrDefault 함수 안에서 "FrontPage" 상수를 사용하는 방법도 있다. 하지만 그러면 기대와는 달리 잘 알려진 상수가 적절하지 않은 저차원 함수에 묻힌다. 상수를 알아야 마땅한 함수에서 실제로 사용하는 함수로 상수를 넘겨주는 방법이 더 좋다.

// WikiPageResponder.ts
...
public makeResponse(context: FitNessContext, request: Request) {
    const pageName = getPageNameOrDefault(request, "FrontPage");
    this.loadPage(pageName, context);
    if (!this.page) {
        return this.notFoundResponse(context, request);
    else
        return this.makePageResponse(context);
}
...

 

- 친화도가 높을수록 코드를 가까이 배치한다. 친화도가 높은 요인은 아래와 같다.

• 한 함수가 다른 함수를 호출해 생기는 직접적인 종속성
• 비슷한 동작을 수행하는 일군의 함수

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

 

- 프로그래머는 명백하게 짧은 행을 선호한다.

 

- 선언부가 길다면 클래스를 쪼개야 한다

 

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

 

- 좋은 소프트웨어 시스템은 읽기 쉬운 문서로 이뤄진다는 사실을 기억하기 바란다. 스타일은 일관적이고 매끄러워야 한다. 한 소스 파일에서 봤던 형식이 다른 소스 파일에도 쓰이리라는 신뢰감을 독자에게 줘야 한다. 온갖 스타일을 뒤섞어 소스 코드를 필요 이상으로 복잡하게 만드는 실수는 반드시 피한다.

6장. 객체와 자료 구조

- 변수 사이에 함수라는 계층을 넣는다고 구현이 저절로 감춰지지는 않는다. 구현을 감추려면 추상화가 필요하다! 그저 (형식 논리에 치우쳐) 조회 함수와 설정 함수로 변수를 다룬다고 클래스가 되지는 않는다. 그보다는 추상 인터페이스를 제공해 사용자가 구현을 모른 채 자료의 핵심을 조작할 수 있어야 진정한 의미의 클래스다.

 

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

- (부연 설명) 조회/설정함수 = getter/setter 

 

- 객체는 추상화 뒤로 자료를 숨긴 채 자료를 다루는 함수만 공개한다. 자료 구조는 자료를 그대로 공개하며 별다른 함수는 제공하지 않는다. 두 정의는 본질적으로 상반된다. 두 개념은 사실상 정반대다. 사소한 차이로 보일지 모르지만 그 차이가 미치는 영향은 굉장하다.

 

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

 

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

-> (부연 설명) 부모 인터페이스에 새로운 함수 정의를 추가할 경우 이를 구현한 수많은 클래스들에 새로운 함수를 추가해야 한다.

 

- 디미터 법칙은 잘 알려진 휴리스틱으로, 모듈은 자신이 조작하는 객체의 속사정을 몰라야 한다는 법칙이다. 객체는 조회 함수로 내부 구조를 공개하면 안된다. 그러면 내부 구조를 (숨기지 않고) 노출하는 셈이니까.

 

- 자료 구조는 무조건 함수 없이 공개 변수만 포함하고 객체는 비공개 변수와 공개 함수를 포함한다면, 문제는 훨씬 간단하리라. 하지만 단순한 자료 구조에도 조회 함수와 설정 함수를 정의하라 요구하는 프레임워크와 표준(예, '빈Bean')이 존재한다.

 

- 잡종 구조는 새로운 함수는 물론이고 새로운 자료 구조도 추가하기 어렵다. 양쪽 세상에서 단점만 모아놓은 구조다. 그러므로 잡종 구조는 되도록 피하는 편이 좋다. 프로그래머가 함수나 타입을 보호할지 공개할지 확신하지 못해 (더 나쁘게는 무지해) 어중간하게 내놓은 설계에 불과하다.

 

- 자료 구조체의 전형적인 형태는 공개 변수만 있고 함수가 없는 클래스다. 흔히 DTO는 데이터베이스에 저장된 가공되지 않은 정보를 애플리케이션 코드에서 사용할 객체로 변환하는 일련의 단계에서 가장 처음으로 사용하는 구조체다. 좀 더 일반적인 형태는 '빈Bean'구조다. 빈은 비공개private 변수를 조회/설정 함수로 조작한다. 일종의 사이비 캡슐화로, 일부 OO 순수주의자나 만족시킬 뿐 별다른 이익을 제공하지 않는다.

 

- 활성 레코드(active record)는 데이터베이스 테이블이나 다른 소스에서 자료를 직접 변환한 결과다.

-> (부연 설명) 가령 TypeORM의 Entity 같은 것들.

 

- 객체는 동작을 공개하고 자료를 숨긴다. 그래서 기존 동작을 변경하지 않으면서 새 객체 타입을 추가하기는 쉬운 반면, 기존 객체에 새 동작을 추가하기는 어렵다. 자료 구조는 별다른 동작 없이 자료를 노출한다. 그래서 기존 자료 구조에 새 동작을 추가하기는 쉬우나, 기존 함수에 새 자료 구조를 추가하기는 어렵다.

-> (내 생각) 좀 말이 헷갈림.