클린코드 17장 Smells and Heuristics

[hyeonjoo]

그동안 다뤄온 내용을 간단하게 정리해보는 장이다.

주석

• 적절한 정보 담기. 코드와 설계에 관하여 technical하게 내용을 적는 공간이어야 한다. 안좋은 예: Source code control system, issue tracking system, 작성자
• 시간이 지나도 변하지 않는 정보 담기. 코드를 수정하다가 주석 수정은 잊어버릴 수 있기 때문에, 주석은 오래된 정보가 되기 쉽다. 만약 오래된 내용을 발견했다면, 업데이트하거나 삭제한다.
• 코드와 같은 내용은 담지 않기. 코드로 충분히 알수 있는 내용을 주석에 담는건 과하다.
• 단어, 문법, 구두법을 신경써서 간결하게 잘 작성하기. 알잘딱깔쎈?
• 주석처리한 코드를 보았다면 삭제하기. 어차피 source code control system이 기록하고 있으니 그 코드가 필요하다면 언제든 다시 불러올 수 있다.

환경

• 간단한 빌드와 테스트 단계. 여러 단계를 거치지 않고 단 하나의 command로 전체 빌드, 전체 테스트가 실행되어야 한다.

함수

• 최소한의 arguments
• Output arguments 피하기
• Flag arguments 피하기. Flag arguments를 가지는 함수라면, 그 함수는 하는일이 많다는 뜻이다.
• 안쓰는 함수 없애기

일반

• 하나의 소스코드에는 하나의 언어만 담기
• 예상되는 동작이 담기도록 함수/클래스 구현하기. The Principle of Least Surprise.
• Boundary condition에 주의하기. 직관에 의존하지 말고 모든 boundary condition을 살피고 테스트도 작성하자.
• Overridden Safeties. Safety warning 절대 무시하지 않기. 컴파일러, 테스트 실패 warning 등
• 중복 제거. 이 책의 가장 중요한 법칙 중 하나. DRY(Don't Repeat Yourself). 중복 코드가 있으면, 추상화할 기회라는 것이다. 내가 추상화 단계를 높여두면, 다른 개발자들이 빨리 코딩할 수 있고 에러도 줄어든다. Switch/case, if/else 체인은 다형성(polymorphism)으로 바꿀 수 있다.(?)
• 추상화 단계에 맞는 코드 짜기. 잘못된 예: 베이스 클래스에 상수, 변수, 유틸함수 같은 구체적인 구현체에 들어가야할 것들을 넣는 것
• 너무 많은 정보 담지 않기. 모듈이 잘 정의되어있다면 작은 인터페이스만 가질 것이다. 과하게 많은 함수를 갖고 있지 않을 것이므로 커플링정도도 낮을 것이다. 인터페이스에 무엇을 드러낼 것인지에 대한 limit 설정을 잘 하면 좋은 개발자.
• 변수는 사용되는 함수 근처 가까이에 정의하기.
• 일관성 갖추기. 비슷한 동작을 한다면 비슷한 방식으로 구현한다. The Principle of Least Surprise.
• 고의적 커플링 피하기. 종속성이 없는데도 편의를 위해서 커플링하는건 피해야한다.
• Feature Envy.

public class HourlyPayCalculator {
    public Money calculateWeeklyPay(HourlyEmployee e) {
        int tenthRate = e.getTenthRate().getPennies();
        int tenthsWorked = e.getTenthsWorked();
        int straightTime = Math.min(400, tenthsWorked);
        int overTime = Math.max(0, tenthsWorked - straightTime); int straightPay = straightTime * tenthRate;
        int overtimePay = (int)Math.round(overTime*tenthRate*1.5);
        return new Money(straightPay + overtimePay);
    }
}

calculateWeeklyPay가 HourlyEmployee의 데이터를 여러번 가져온다. 차라리 이 함수가 HourlyEmployee 안에 있으면 클래스의 데이터를 외부로 노출시키지 않을 수 있게 되고 feature envy를 제거할 수 있게 된다. Feature envy를 제거하는 것이 마냥 좋을 것 같지만 사실 주의를 요하는 작업이다. 다음 예시를 보자.

public class HourlyEmployeeReport {
    private HourlyEmployee employee ;
    public HourlyEmployeeReport(HourlyEmployee e) {
        this.employee = e;
    }
    String reportHours() {
        return String.format(
            "Name: %s\tHours:%d.%1d\n", employee.getName(), employee.getTenthsWorked()/10, employee.getTenthsWorked()%10);
    }
}

reportHours가 HourlyEmployee에 있는게 이상적으로 보인다. 하지만 HourlyEmployee는 report format을 알 필요가 없다. feature envy를 제거하면, HourlyEmployee가 report format에 커플링이 생겨버린다.

Java

• 긴 Import lines 피하기. Bulk import 하기. IDE가 잘 접어줘서 이제는 크게 상관없는데.. 명시적 import가 낫지 않나? 한번 이야기 나누고 싶은 부분.
• Constant는 상속되지 않게 따로 분리하기. 부모 클래스에 종속된 constant는 계속 상속이 될 수 있고 그럼 자식의 자식의 자식 클래스는 그 constant가 정의된 곳을 찾기 위해 상속 체인을 타고타고 올라가야 한다. 상수는 분리해서 static import하자. 예시: import static PayrollConstants.*;
• Constant말고 enum쓰기. Java의 enum은 method와 field가 들어갈 수 있으니 문법에 주의할 것. Enum의 표현력과 융통성은 단순 상수(public static final int)보다 강력하다.

네이밍

• 설명이 충분히 되는 이름을 고르기. 시간을 충분히 들여서 이름을 신중하게 잘 고르면, 코드 구조가 이름에 드러나게 된다. 그렇게 되면 코드가 직관성을 갖게 된다. (It will be pretty much what you expected.)
• 추상화 정도에 맞는 이름 고르기.

public interface Modem {
    boolean dial(String phoneNumber); boolean disconnect();
    boolean send(char c);
    char recv();
    String getConnectedPhoneNumber();
}

만약 위와 같은 모뎀 인터페이스가 있는데, 어떤 프로그램에서는 dial이 아닌 인터넷 선으로 연결하는 모뎀일 수 가 있다. 그러니 범용성을 갖추기 위해서 위의 모뎀은 다음과 같이 renaming이 필요하다.

public interface Modem {
    boolean connect(String connectionLocator); boolean disconnect();
    boolean send(char c);
    char recv();
    String getConnectedLocator();
}

관련 회사 경험이 하나 있는데... integrate하는 브랜드(Postgre, Microsoft, Amazon 등) 아이콘이 있고, 그 아이콘들은 connection에 쓰이는 것들이라서 prefix가 connection 이었다. 기능 구현팀에서는 이름을 기능 구현 의도를 살려서 그대로 두고 싶은데 디자인시스템 팀에서는 prefix를 logo 로 바꿨다.

• 회사 모든 개발자가 알만한 단어 사용하기. 개발자들이 아는 term도 좋은데 사내 term이 있다면 그걸 사용하면 더 쉽게 코드를 설명할 수 있다.
• 애매모호한 이름 쓰지 않기. 예) doRename() 대신 renamePageAndOptionallyAllReferences(). 길어도 이게 낫다.
• Long names for Long Scopes. 간단한 한 줄짜리 for문 이라면 i를 써도 큰 문제가 없지만 긴 line을 다뤄야한다면 변수명이 길어져야 한다.
• 인코딩 피하기. m_, f, vis_ for visual imaging system 같은 prefix 피하기.
• Side effect가 표현되게 이름짓기.

public ObjectOutputStream getOos() throws IOException { if (m_oos == null) {
    m_oos = new ObjectOutputStream(m_socket.getOutputStream()); }
    return m_oos;
}

위의 경우 단순히 Oos(ObjectOutputStream)를 리턴하는 함수가 아니다. ObjectOutputStream이 없으면 새로 만들기도 하기 때문에, getOos보다는 createOrReturnOos라고 이름짓는 게 낫다.

테스트

• 충분한 테스트. 단순히 "음, 충분한 것 같은데?" 라고 판단하고 넘길 것이 아니라 오류가 발생할 수 있는 모든 곳을 테스트 해야한다.
• 커버리지 테스트 툴 사용하기
• 자잘한 테스트 그냥 넘기지 않기
• Test boundary condition 설정에 주의하기
• 버그가 발생했다면 그 함수를 철저하게 테스트하기. 버그 하나 발생했다고 하나만 있는게 아닐 수 있다. 아마 몇개 더 찾을걸
• 실패한 테스트에서 패턴 찾기. 테스트 케이스가 실패한 흐름에서 패턴을 발견할 수 있고, 거기에서 문제를 진단할 수 있다. 예: 모든 테스트에서 input string이 5자를 넘어갔을 때 fail된다.
• 빠른 테스트

[JeGwan]

클린코드 17장 - 냄새와 휴리스틱

주석

• C1 부적절한 정보 : 다른 시스템에 저장할 정보는 주석으로 적절하지 못하다!
• C2 쓸모 없는 주석
• C3 중복된 주석
• C4 성의 없는 주석 : 주절 대지말자. 간결 명료하게 작성한다
• C5 주석 처리된 코드 : VCS를 믿어라. 바로 지워라

환경

• E1 여러 단계로 빌드해야한다 : 하나의 스크립트로 실행되게 만들자.
• E2 여러 단계로 테스트한다 : 하나의 명령어로 테스트해야하고, 쉽고 빠르고 명백해야한다.

함수

• F1 너무 많은 인수 : 인수는 적을 수록 좋다. 아예 없는게 제일 좋다.
• F2 출력 인수 : 함수의 상태를 변경해야한다면, 함수가 속한 객체의 상태를 변경하자. 출력인수 쓰지말고!
  • 참고. Output argument appendFooter(page) 식으로 output으로 내어야할 결과 대신, 인수 그자체를 바꾸는 것.
• F3 플래그 인수 : 혼란스럽다. 그럴바엔 그냥 함수 두개로 나눠라!
• F4 죽은 함수 : 호출되지 않으면 지워라.

일반

• G1 한 소스 파일에 여러 언어를 사용한다 : 하나만 쓰자.
• G2 당연한 동작을 구현하지 않는다 : 기대대로 동작하게 구현하자. 그래야 쓰는 사람이 여러번 혼란스럽지 않게 된다
  • 최소 놀람의 원칙 : API를 쓰는 사람은 최대한 덜 놀래야(당황스러워야)한다. 즉 대부분이 기대대로 동작해야한다.
• G3 경계를 올바로 처리하지 않는다 : 모든 경계 조건을 찾아내고 모든 경계조건을 테스트하는 케이스를 작성하자.
  • 경계 조건은 더 크리티컬 하니까.
• G4 안전 절차 무시 : 컴파일러 경고, 테스트 실패를 무시하면 자칫 끝없는 디버깅에 시달린다.
• G5 중복 : DRY를 따르자. 추상화로 중복을 정리하면 설계 언어의 어휘가 늘어난다.
• G6 추상화 수준이 올바르지 못하다 :
  • base 클래스는 구현을 몰라야한다.
  • 고차원 개념과 저차원을 섞지말자. (같은 뎁스에 같은 추상화 레벨)
• G7 기초 클래스가 파생 클래스에 의존한다 : 아주 잘못한 거다. 기초 클래스는 파생 클래스를 몰라야한다. 그래야 변경에 용이해진다.
• G8 과도한 정보
  • 잘 정의된 인터페이스는 많은 함수를 제공하지 않는다.
  • 따라서 결합도(Coupling)가 낮다.
  • 인터페이스를 매우 작고 깐깐하게 만들자.
  • 정보를 제한해 결합도를 낮추자.
• G9 죽은 코드 : 지우자
• G10 수직 분리 : 변수는 쓰이는 함수에 가깝게, 프라이빗 메서드는 호출부 직후에
• G11 일관성 부족 : 최소 놀람의 원칙! 일관성만으로도 코드를 읽고 수정하기 쉬워진다.
• G12 잡동사니 : 지워라
• G13 인위적 결합 : 서로 무관한 개념을 결합하지 말아라.
• G14 기능 욕심 : 메서드가 다른 객체의 메서드를 사용해 객체 내용을 조작한다면 자신의 범위를 넘어서 욕심을 내는 것이다. feat. 디미터의 법칙
• G15 선택자 인수 (불리언으로 끄고 켜는) : 함수 여러개로 쪼개라.
• G16 모호한 의도 : 의도를 분명하게 정하고 밝히자.
• G17 잘못 위치시킨 책임 : 관련성 있는 클래스, 메서드, 상수가 모여있어야 한다. 쓰는 사람이 기대하는 곳에 있어야 한다.
• G18 부적절한 static 메서드
  • 구현이 달라질 필요가 생기면(다형성으로 override 할 필요성이 생기면) 곤란해진다.
  • 충분한 이유 없이는 인스턴스 메서드로 만들자.
• G19 서술적 변수 : 읽기 쉽게 만들자.
• G20 이름과 기능이 일치하는 함수 : 네이밍 잘하자
• G21 알고리즘을 이해하라 : 구현이 끝났다고 선언하기 전에 함수가 돌아가는 방식을 확실히 이해했는지 확인하라.
• G22 Make logical dependency physical
  • B 클래스에서 쓰일 로직을 A가 들고 있다면, B클래스 내부로 옮기는게 맞다.
  • 즉 A내부에 B에 대한 논리(로직) 의존성이 생기면, 아예 물리화 시켜 B로 옮기자.
• G23 if/else, switch/case 보다 다형성을 사용하자
• G24 표준 컨벤션을 따르자
• G25 매직넘버는 이름있는 상수로 바꾸자
• G26 정확하자(Be Precise)
  • 코드에서 결정은 정확해야한다.
  • 결정을 내리는 이유와 예외를 처리할 방법을 분명히 알아야한다.
• G27 Structure over Convention
  • 관례를 지키게 하기보다 아예 구조화 시키자(코드로서의, 린트로서의 강제)
• G28 조건을 캡슐화하자.
• G29 부정 조건은 피하자. shouldCompact > shouldNotCompact
• G30 Function should do one thing
• G31 순차적 의존을 숨기지말자 : A -> B -> C 메서드가 순차 실행해야한다면, 이러한 의존성을 파이프라인처럼 선행의 아웃풋이 후행의 인풋으로 만들어 가시화 시키자.
• G32 일관성을 유지하라.
• G33 경계조건을 캡슐화하자.
• G34 함수는 추상화 수준을 한단계만 내려가야한다.
  • 그 추상화 수준은 함수이름이 의미하는 작업보다 한 단계만 낮아야 한다.
• G35 설정 정보는 최상위 단계에 두자.
  • 그래야 변경도 쉽다.
  • 저차원 함수에 상수값을 정의하지말자.
• G36 추이적 탐색을 피하라
  • 디미터의 법칙
  • 직접 사용하는 모듈만 알아야 한다.
  • 한 모듈이 너무 많은 아키텍쳐를 알면 안된다. 그럼 아키텍쳐가 굳어지게 된다.
  • 이상적으로는 myCollaborator.doSomething() 형태의 코드만 있어야한다.

자바

• J1 긴 import 목록을 피하고 와일드 카드를 설정하라 : JS도 같나?
• J2 상수는 상속하지 않는다 : 상수는 구현에서 정해야한다. 추상 클래스는 blueprint만 되어야한다.
• J3 상수보다 enum 잘 쓰자.

이름

• N1 Choose descriptive name
• N2 적절한 추상화 수준의 이름을 선택하자.
• N3 표준 명명법을 사용하자
  • 프로젝트에 유효한 의미가 담긴 이름을 많이 사용할 수록 독자가 코드를 이해하기 쉬워진다. (DSL?)
• N4 명확한 이름
  • 변수명이 길어져도 길다는 단점을 서술성이 메꾼다.
• N5 긴 스코프에서는 긴 이름을 사용하자
• N6 인코딩을 피하라 : 헝가리안 노테이션 따위 필요 없다.
• N7 이름으로 부수효과를 설명하자.
  • getOos() (없으면 생성한다면) => createOrReturnOos()

테스트

• T1 불충분한 테스트 : 잠재적으로 깨질만한 부분들을 모두 테스트하자
• T2 커버리지 도구를 쓰자
• T3 사소한 테스트를 건너뛰지마라
  • 구현에 드는 비용보다 사소한 테스트가 제공하는 문서적 가치가 더크다.
• T4 무시한 테스트는 모호함을 뜻한다.
• T5 경계 조건을 테스트한다.
• T6 버그 주변은 철처히 테스트한다.
• T7 실패 패턴을 보자 : 문제 진단이 쉽다.
• T8 테스트 커버리지 패턴을 보자
  • 통과하는 테스트가 실행하거나 실행하지 않는 코드를 보면 실패 케이스의 실패 원인이 드러난다.
• T9 테스트는 빨라야한다.