[클린 코드] 2. 주석 및 포맷팅(formatting)

Posted on | In
[파이썬에서의 깔끔한 코드] 관용적인 주석과 버티컬/호라이즌탈 포매팅의 개념

주석

  • 모든 내용을 주석으로 넣게 되면 코드가 지저분할 수 있다.
  • 대부분 좋은 네이밍으로 충분히 해결할 수 있다.

  • 네이밍으로 표현할 수 없는 영역은 주석으로 표현해주면 된다.

  • 법적인 정보를 담을 때
1
# Copyright (C) 2021 ...
  • 의도를 명확하게 설명할 때
1
2
3
4
5
# throughput을 늘리기 위해 스레드를 10개까지 늘린다.
for idx in range(10):
    thread = threading.Thread(target=...)
    thread.start()
...
  • 중요성을 강조할 때
1
2
3
# 최종 결제를 하기 전에 진행해야 하는 validation 함수 
def validate_buyable(wallet, price, ...):
    ...
  • 결과를 경고할 때
1
2
3
# WARNING: API 서버가 항상 양호한지 알 수 없음.
def connect_api_server():
    ...

관용적으로 사용되는 키워드

  • TODO: 당장은 아니지만 다음에 해야 할 때
  • FIXME: 치명적인 에러를 발생하는 코드는 아니지만 수정해야 할 때
  • XXX: 더 생각해볼 필요가 있을 때
1
2
3
4
5
6
7
8
# TODO@6mini: 객체의 책임 더 분리하기
class 6miniStore:
    ...
    # FIXME: 반복문의 depth 줄이기 
    def sell_food(self):
        for food in food_list:
            for discount in discount_list:
                ...

포맷팅

버티컬 포맷팅(Vertical Formatting)

  • 한 파일에 코드를 다 넣지 말고, 개념에 맞게 파일을 나눠서 사용한다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# as-is 
# store.py에 전부 있음
class FruitsStore:
    ...

class ComputerStore:
    ...

# to-be
# fruit_store.py
class FruitsStore:
    ...

# computer_store.py
class ComputerStore:
    ...
  • 다른 개념의 코드는 스페이싱(spacing)으로 분리한다.
  • 비슷한 개념의 코드는 붙여서 사용한다.
1
2
3
4
5
6
7
8
def test_user_buy_product():
    user = User()
    product = Product()
    
    product.set_sold_out(True)
    user.get(product)
    
    assert result == "success"

호라이즌탈 포맷팅(Horizontal Formatting)

  • 한 줄에 코드를 다 넣기보단 변수 등을 활용해서 가독성을 높인다.
1
2
3
4
5
6
# as-is
product_list.extend([Product("모니터"), Product("키보드"), Product("노트북")])

# to-be
items = [Product("모니터"), Product("키보드"), Product("노트북")]
product_list.extend(items)
  • 네이밍을 잘하여 길이를 줄인다.
1
2
3
4
user_with_name_and_email = User("6mini", "6mini@world.com")

#to-be
user = User("6mini", "6mini@world.com")
0%