Clean Code - cleancodeclass/cleancode_theory GitHub Wiki

I like my code to be elegant and efficient. The logic should be straightforward and make it hard for bugs to hide, the dependencies minimal to ease maintenance, error handling complete according to an articulated strategy, and performance close to optimal so as not to tempt people to make the code messy with unprincipled optimizations. Clean code does one thing well.

Clean code is simple and direct. Clean code reads like well-written prose. **Clean code never obscures the designers intent ** but rather is full of crisp abstractions and straightforward lines of control.

모든 팀원이 이해(understandability)하기 쉽도록 작성된 코드

• 의존성이 적어 단순하고, 테스트코드로 검증된 코드
• 코드를 해석하는 시간과 수정하는 시간의 비율은 10(read) : 1 (write)
• 대부분의 결함은 기존 코드 수정 시에 발생되므로 이해하기 쉬운 코드는 오류의 위험을 최소화함

https://www.planetgeek.ch/wp-content/uploads/2014/11/Clean-Code-V2.4.pdf

Robert C Martion - Clean Code

• Write BETTER Code! 7 Tips to Improve Your Programming Skills : https://youtu.be/vfqvzgkYYF0?list=PLWEGSwIIXaWDPEjAjBaaCph9tJRddgUpW
• Coding is not difficult | Mark Zukerberg : https://youtu.be/F9GujgK0y2M?list=PLWEGSwIIXaWDPEjAjBaaCph9tJRddgUpW

1. Naming

• 의도를 분명히 밝혀 Naming 하라

• 변수나 함수의 클래스의 존재의 이유와 사용방법등을 알기 쉽게 작성해야 한다
• 코드가 하는 일을 짐작하기 쉽게 작성해야 한다

//나쁜 예
int d; // 경과 시간
// d는 아무런 의미가 드러나지도 않으며 경과시간이나 날짜 수라는 느낌도 들지 않는다.

//좋은 예
int elapsedTimeInDays;
int daysSinceCreation;
int fileAgeInDays;
// 해당 변수가 어떠한 역할을 하는지 알기 쉽다.

• 잘못된 정보를 피해서 Naming 하라.

• Naming 시에 잘못된 의미를 담은 단어를 사용해서는 안된다.
• 서로 흡사한 이름이를 사용하지 않도록 주의한다.

//나쁜 예
//계정 그룹을 표현하고자 했지만 List의 의미가 잘못 전달될 수 있다.
 accountList
//흡사한 이름은 혼동을 줄수 있다.
 XYZControllerForEfficientHandllingOfStrings , XYZControllerForEfficientStorageOfStrings (구분이 쉽지 않다)

//좋은 예
//계정 그룹을 표현한다면 
 accountGroup, bunchOfAccouns, 혹은 단순히 accounts 라고 명명한다.

2. Method

• 함수는 한가지 역할만을 수행해야 한다.
  • 함수는 한 가지를 해야 한다. 그 한 가지를 잘 해야 한다. 그 한 가지만을 해야 한다.
  • 이 부분에서 문제가 된다면, 그것은 그 '한 가지'가 무엇인지 알기가 어렵다는 점이다.
  • 이에 대해 간단한 팁을 주자면, 지정된 함수 이름 아래서 추상화 수준이 하나인 단계만 수행한다면 그 함수는 한가지 작업만 한다고 볼 > 수 있다.
  • 어쨋거나 우리가 함수를 만드는 이유는 큰 개념을 다음 추상화 수준에서 여러 단계로 나눠 수행하기 위해서가 아니던가.
  • 따라서 함수가 '한 가지'만 하는지 판단하려면 해당 함수 내에서 의미 있는 이름으로 다른 함수를 추출할 수 있다면 그 함수는 여러 작업을 하는 셈이다.
• Switch보다 다형성(polymorphism) 사용
  • switch 문은 작게 만들기 어렵다. 또한 '한 가지' 작업만 하는 switch 문도 만들기 어렵다. 본질적으로 switch 문은 N가지를 처리한다.

public Money calculatePay(Employee e) throws InvalidEmployeeType {
    switch (e.type) {
        case COMMISSIONED:
            return calculateCommissionedPay(e);
        case HOURLY:
            return calculateHourlyPay(e);
        case SALARIED:
            return calculateSalariedPay(e);
        default:
            throw new InvalidEmployeeType(e.type);
    }
}

위 함수에는 몇 가지 문제가 있다. 첫째, 함수가 길다. 새 직원 유형을 추가하면 더 길어진다. 둘째, '한 가지' 작업만 수행하지 않는다. 셋째, SRP(Single Responsibliity Principle)를 위반한다. 코드를 변경할 이유가 여럿이기 때문이다. 네째, OCP(Open Closed Principle)를 위반한다. 새 직원 유형을 추가할 때마다 코드를 변경하기 때문이다. 하지만 아마 가장 심각한 문제라면 위 함수와 구조가 동일한 함수가 무한정 존재한다는 사실이다.

이 문제를 해결한 코드가 아래 코드 이다. 아래 코드는 switch 문을 추상 팩토리에 꽁꽁 숨긴다. 아무에게도 보여주지 않는다.

팩토리는 switch 문을 사용해 적절한 Employee 파생 클래스의 인스턴스를 생성한다.; calculatePay, isPayday, deliverPay 등과 같은 함수는 Employee 인터페이스를 거쳐 호출된다.

그러면 다형성으로 인해 실제 파생 클래스의 함수가 실행된다.

public abstract class Employee {
    public abstract boolean isPayday();
    public abstract Money calculatePay();
    public abstract void deliverPay(Money pay);
}

public interface EmployeeFactory {
    public Employee makeEmployee(EmployeeRecord r) throws InvalidEmployeeType;
}

public class EmployeeFactoryImpl implements EmployeeFactory {
    public Employee makeEmployee(EmployeeRecord r) throws InvalidEmployeeType {
        switch (r.type) {
            case COMMISSIONED:
                return new CommissionedEmployee(r);
            case HOURLY;
                return new HourlyEmployee(r);
            case SALARIED:
                return new SalariedEmployee(r);
            default:
                throw new ImvalidEmployeeType(r.type);
        }
    }
}

• 함수 인수 최소화
  • 가급적이면 4개 이상의 인자를 피하도록 한다.

3. Comment

• 주석으로 나쁜 코드를 보완하지 말고, 코드로 의도를 표현하라.
• 나쁜 주석
  • 특별한 이유 없이 의무감으로 다는 주석
  • 코드의 내용을 그대로 반복하는 중복적인 주석 (javadoc 포함)
  • 주석으로 처리된 코드: 대부분이 주석으로 제거된 코드는 다시 사용되지 않는다.
• 좋은 주석
  • 법적인 주석 (저작권, 사용권 등)
  • 구체적인 정보와 의도를 설명하는 주석
  • 결과를 경고하는 주석 (eg: “여유 시간이 충분하지 않다면 실행하지 마십시오.”)
  • TODO, 공개 API에 대한 Javadocs 등

4. Style

• 적절한 행 길이를 유지하라.(빈 행을 추가하도록 한다.)

package fitnesse.wikitext.widgets;

import java.util.regex.*;

public class BoldWidget extends ParentWidget {
    public static final String REGEXP = "'''.+?'''";
    private static final Pattern pattern = Pattern.compile("'''(.+?)'''", 
        Pattern.MULTILINE + Pattern.DOTALL
    );

    public BoldWidget(ParentWidget parent, String text) throws Exception { 
        super(parent);
        Matcher match = pattern.matcher(text);
        match.find();
        addChildWidgets(match.group(1)); 
    }

    public String render() throws Exception { 
        StringBuffer html = new StringBuffer(""); 
        html.append(childHtml()).append(""); 
        return html.toString();
    } 
}

• 관련항목간의 거리를 최소화한다.
  • 변수는 사용하는 위치에 최대한 가까이 선언한다.
  • 종속 관계의 함수는 세로로 가까이 배치한다.
• 들여 쓰기 잘하기

5. Data Structures

• 자료는 추상화를 통해 내부 구현 정보를 노출하지 말아야 한다.

public class Point {
    public double x;
    public double y;
} 

public interface Point {
    double getX();
    double getY();
    void setCartesian(double x, double y));
    double getR();
    double getTheta();
    void setPolar(double r, double theta);
}

6. Class

• 높은 응집도를 유지하도록 한다.
  • 클래스는 인스턴스 변수가 적어야 하며, 메소드가 변수를 더 많이 사용할 수록 응집도가 높다.
  • 응집도를 유지하면, 작은 단일 역할 클래스로 분리가 가능.

7. Error Handling

• Null을 반환하거나 파라미터로 넘기는 것은 지양하라.(빈 객체 등을 전달)
• Unchecked Exception을 사용하라.
  • Checked Exception은 불필요한 예외 처리를 갖게 되기 때문에 되도록 지양하라.
  • Error는 시스템에 비정상적인 상황이 생겼을 때 발생한다. 이는 시스템 레벨에서 발생하기 때문에 심각한 수준의 오류이다. 따라서 개발자가 미리 예측하여 처리할 수 없기 때문에, 애플리케이션에서 오류에 대한 처리를 신경 쓰지 않아도 된다.
  • 예외(Exception)는 개발자가 구현한 로직에서 발생한다. 즉, 예외는 발생할 상황을 미리 예측하여 처리할 수 있다. 즉, 예외는 개발자가 처리할 수 있기 때문에 예외를 구분하고 그에 따른 처리 방법을 명확히 알고 적용하는 것이 중요하다.

8. Unit Tests

• 테스트코드 작성 및 , 지속적인 유지를 통해 코드에 대한 유연성, 유지보수성 및 재사용성을 확보한다.
• 깨끗한 테스트의 다섯 가지 원칙(F.I.R.S.T)
  • Fast : 테스트는 빨라야 한다. 그렇지 않으면 자주 돌릴 엄두를 못내고, 결국 불필요한 테스트가 된다.
  • Independent : 각 테스트는 서로 의존하면 안된다. 의존적인 경우 실패의 원인 파악이 어렵다.
  • Repeatable : 테스트는 어떤 환경에서도 반복 실행 가능해야 한다.
  • Self-Validating : 테스트 boolean 값으로 결과를 내야 한다. 그렇지 않으면, 자동화에 걸림돌이 된다.
  • Timely : 테스트는 적시에 작성해야 한다. 실제 코드 직전에 작성해야 적절한 코드가 작성된다.