좋은 파이썬 코드 작성을 위한 필독 - 파이썬 스타일 가이드 PEP8

 

파이썬 스타일 가이드 PEP8에 대해

PEP는 Python Enhancement Proposal의 약자로, 그 중 8번째에 해당하는 것을 PEP8이라고 한다.

파이썬의 창시자인 Guido Van Rossum에 의해 제안된 PEP8은 파이썬 스타일 가이드를 제안하고 있다.

PEP8 스타일의 파이썬 코드를 작성하다 보면, 가독성이 좋은 파이썬 코드를 작성하게 될 것이므로 파이썬 개발자라면 당연히 참고해야할 가이드라 할 수 있다.

본 글에서는, PEP8 가이드 중의 일부 항목을 살펴보고 소개하고자 한다.

 

스타일 가이드의 필요성

스타일 가이드는 쉽게 말하면, 일종의 규약 가이드이다.

여러 개발자들이 저마다의 경력과 백그라운드 및 경험이 다를텐데, 이 사람들이 모여서 프로젝트를 하다보면 자기만의 익숙한 스타일로 코딩을 하게 된다.

물론, 모두 최선을 다하겠지만 이것이 항상 좋은 결과로 이어지는 것은 아니다.

결국, 프로젝트를 진행하면서 본의 아니게, 엉망인 프로젝트로 향할 가능성이 높아진다.

스타일 가이드에서 의도하는 바는, 항상 이렇게 하라는 것이라기 보다는 개발자들이 접하게 되는 어떤 선택적인 상황에 대해 아이디어를 제공하고 이렇게 하면 좋겠다고 제시를 하는 것에 가깝다.

많은 사람들이 이러한 스타일 가이드를 따르게 되면, 비슷한 관행으로 프로그램을 작성할 것이다.

그러면, 프로젝트의 관행상 유사율이 높아지고, 가독성과 유지보수성이 높아진다.

 

반응형

 

작명법 (Naming Conventions)

모듈, 클래스, 함수, 변수 등의 작명법에 대한 가이드는 아래와 같다.

 

패키지/모듈

• 가급적이면 이름을 짧게 만든다.
• 패키지나 모듈 이름은 모두 소문자로만 작성한다.
• 모듈 이름이 길어지면 밑줄(underscore)를 사용할 수 있다.
• 패키지 이름에는 밑줄(unserscore)도 사용하지 않는다.

# 패키지 이름
import mypackage

# 모듈 이름
my_long_module.py

 

클래스

• 클래스 이름은 CapWord(CamelCase)로 작성한다.
• Exception 클래스의 경우 이름+Error를 관행으로 한다.

# Class 예
class MyClass:
    pass

# Exception Class 예
class MyCustomError(Exception):
    """My Custom Exception"""

 

메소드

• 메소드 이름은 snake_tail 방식으로 작성한다. (underscore 사용할 것)
• 인스턴스 메소드의 첫 번째 인자는 항상 self로 시작한다.
• 클래스 메소드의 첫 번쨰 인자는 항상 cls로 시작한다.

class MyClass:
    def instance_method(self):
        pass

    @classmethod
    def class_method(cls):
        pass

 

상수

• 상수는 대문자로만 작성한다.
• 이름이 길어지는 경우, 밑줄(underscore)로 단어간 구분한다.

PI = 3.14
LONG_CONSTANT_EXAMPLE = 12345678

 

레이아웃

파이썬 코드의 레이아웃으로 다음의 룰들을 소개한다.

 

import

• import 문은 한 줄에 하나씩 쓰는 것을 기본 원칙으로 한다.
• 보통 파일의 제일 위에 기록한다.
• 여러 라이브러리를 import할 때는 아래 순서들을 유지하여 기록한다.
  • 표준 라이브러리
  • 관련된 3rd party 라이브러리
  • 로컬 애플리케이션 및 특정 라이브러리에 특화된 import

  # good
  import os
  import sys
  
  # bad
  import os, sys

 

indent

• 들여쓰기 별로 4칸씩 띄어쓰기를 꼭 지킨다.
• 함수의 줄 바꿈시에는 가독성을 위해 구분이 가능하도록 한다.

#  good
# 파라미터 위치를 맞추는 경우
do_something(param1, param2,
             param3, param4)

# 한 레벨 더 들여쓰기를 해서 가독성을 높임
def do_something(
        param1, param2, param3,
        param4, param5):
    pass

# bad
# 세로 줄을 안 맞추는 경우
result = do_something(param1, param2,
     param3, param4)

# 추가로 들여쓰기를 해서 가독성을 높여야 하는 경우
def do_somthing(
    param1, param2, param3,
    param4, param5):
    pass

 

tab 또는 space

• 탭보다 스페이스를 선호한다.
• 탭과 스페이스, 둘을 섞어서 쓰지 말자.

 

폭 길이/ 줄 바꿈

• 가독성/ 유지보수성을 위해 한 줄의 최대 글자수는 79자까지만 허용한다.
• 주석 등은 72자까지만 허용한다.
• 그 이상 되는 문자열은 줄 바꿈 기능을 사용하여 추가 기록한다.

 

빈 줄 넣기 (blank lines)

• top-level 클래스나 함수들은 그 밖의 코드들과 두 줄로 분리한다.
• 클래스 내의 함수들간은 한 줄로 구분한다.
• 클래스 내에서는 가급적이면 빈 줄은 넣지 않지만, 논리적으로 구분이 되는 부분에서 한 줄을 띄워넣어서 가독성을 높여도 좋다.

 

이항 연산자(binary operator)를 여러 줄에 걸쳐 쓰는 경우

• 이항 연산이 길게 나열되는 경우, 과거에는 연산자를 윗줄에 썼으나 가독성 향상을 위해 아랫줄에 연산자를 쓰는 것으로 한다.

# good
sum = (value1
        + value2
        + value3
        + value4)

# bad
sum = (value1 +
        value2 +
        value3 +
        value4)

 

 

 

주석

• 코드상 의도가 분명하여 설명이 필요없는 경우는 불필요한 주석을 달지 않는다.
• 주석은 대문자로 시작한다. (영어 표기시)
• 완벽한 문장(full sentence)으로 작성한다.
• 코드 변경이 있을 떄마다 업데이트 하여, 주석 내용이 항상 최신이 되도록 유지한다. 코드 내용과 반대되는 주석은 없는 것만 못하다.
• 만약, 당신의 코드가 절대로 외국인들에게 읽히지 않을 것이라고 120% 확신하지 않는 한, 주석은 가급적 영어로 남기자. (라고 써 있음)

 

블럭 주석 (block comment)

• 바로 뒤에 오는 코드에 대해 설명한다.
• 주석 내용이 다루는 코드와 동일한 들여쓰기 레벨에서 표기한다.
• 한 개의 #를 달고 주석을 기록한다.

# Need to verify user inputs by rules.
verify_by_rules(user_inputs)
normalized_data = normalizednormalize_data(user_inputs)

 

인라인 주석 (inline comment)

• 코드랑 같은 줄에 기록하는 주석이다.
• 코드와 적어도 두 칸 이상을 분리한 후 기록한다.
• #를 붙인 후, 내용을 기록한다.
• 너무 명확한 것은 굳이 주석을 남기지 않는다.

result_dict = {}  # It will hold the calculation result from the operation.

 

도큐먼트 스트링 (docstrings)

• 모듈, 클래스, 함수, 메소드 등에 대해 정보를 제공하는 용도로 사용되며, docstrings라고도 불린다.
• 앞의 다른 주석들과 차이점은 세 개의 쌍따옴표로 문장을 감싼다는 점이다.
• 함수 바로 밑에 그 내용을 적어준다.
• 한 줄인 경우 따옴표들-내용-따옴표들로 표기하는 경우도 있지만, 보통 여러 줄로 표기된다.

def area_rectangle(x, y):
    """Returns the area of a rectangle."""
    return x * y

def area_circle(r):
    """Returns the area of a cricle.
       It's PI x R^2.
    """
    return PI * r**2

 

더 보기

파이썬 공식 PEP8 가이드