견고한 파이썬 | 위니북스

자주 사용하는 파이썬 컨벤션

파이썬 컨벤션은 코드를 더 읽기 쉽고 유지보수하기 쉽게 만드는 권장 사항입니다. 이러한 컨벤션을 따르면 코드의 일관성을 유지하고, 다른 개발자와의 협업을 용이하게 할 수 있습니다.

아래와 같은 글로벌 기업의 스타일가이드를 읽는 것도 큰 도움이 됩니다.

styleguide

구글의 스타일 가이드는 영상으로 찍어두었으니 후에 확인해보세요.

[Google Coding 컨벤션] #1 Python 코딩 컨벤션

1. PEP 8 스타일 가이드

PEP 8은 파이썬 코드를 작성할 때 따르는 스타일 가이드입니다. 여기에는 변수명, 함수명, 클래스명 작성법, 들여쓰기, 라인 길이, 공백 사용 등에 대한 권장 사항이 포함되어 있습니다.

변수명과 함수명: 소문자로 작성하며, 단어 사이는 언더스코어(_)로 구분합니다. 예: my_variable, calculate_value
클래스명: 카멜케이스(CamelCase)를 사용합니다. 예: MyClass
상수: 대문자와 언더스코어를 사용합니다. 예: MAX_SIZE, DEFAULT_COLOR
들여쓰기: 공백 4개를 사용합니다. 일부 에디터에서 Tab을 Space 4개로 변환해주지 않는 경우도 있으니 확인이 필요합니다. 또한 colab에 기본 들여쓰기 설정은 Space 2개입니다. 2개여도 작동하는데 문제가 생기진 않습니다.
라인 길이: 한 줄은 최대 79자를 넘지 않도록 합니다. 한글이면 한 줄에 32자가 적당합니다.
공백: 괄호, 콤마, 콜론 앞에는 공백을 넣지 않습니다. 예: func(x, y), if x == 4:

2. 명확한 코드 작성

코드는 가능한 명확하고 간결하게 작성해야 합니다. 파이썬의 철학인 "명료함이 난해함보다 낫다"를 기억하세요.

불필요한 주석 피하기: 코드 자체로 의도가 명확하게 전달되도록 작성합니다.
주석의 위치와 내용:

함수나 클래스에 주석은 Doc String을 사용해야 합니다. 위나 옆에 주석을 달지 않도록 해주세요. 또한 주석을 너무 상세하게 달아 가독성을 해치지 말아주세요. 코드를 읽는 사람이 기본적인 문법을 모른다고 생각하고 주석을 달아서는 안됩니다. 주석은 회사 컨벤션으로 정하는 것을 권합니다. 보통 함수 기능 설명, 파라미터 설명, 반환값 설명, 사용 예시를 넣습니다.

def calculate_area(radius):
    """
    원의 면적을 계산하는 함수.
 
    파라미터:
        radius (float): 원의 반지름
 
    반환값:
        float: 원의 면적
 
    예시:
        >>> calculate_area(5)
        78.53981633974483
    """
    return 3.14159 * radius * radius
 
# 함수 사용 예시
area = calculate_area(5)
print("Area:", area)

def calculate_area(radius):
    """
    원의 면적을 계산하는 함수.
 
    파라미터:
        radius (float): 원의 반지름
 
    반환값:
        float: 원의 면적
 
    예시:
        >>> calculate_area(5)
        78.53981633974483
    """
    return 3.14159 * radius * radius
 
# 함수 사용 예시
area = calculate_area(5)
print("Area:", area)

저작권을 담은 주석은 파일의 맨 위에 작성합니다. 파일의 맨 위에는 파일의 제목, 작성자, 작성일, 수정일, 저작권 정보 등을 작성합니다. 너무 긴 텍스트는 외부의 파일을 참고하도록 합니다.

"""이 코드의 저작권은 위니브에 있습니다. 2024년 1월 30일에 작성되었습니다. 저작권의 상세 내용은 회사 코드 라이센스 문서를 참고하세요."""
def calculate_area(radius):
    return 3.14159 * radius * radius

"""이 코드의 저작권은 위니브에 있습니다. 2024년 1월 30일에 작성되었습니다. 저작권의 상세 내용은 회사 코드 라이센스 문서를 참고하세요."""
def calculate_area(radius):
    return 3.14159 * radius * radius

코드 태그는 TODO만 사용하고 나머지 태그는 되도록 사용하지 않는 것을 권합니다. 예를 들어 FIXME와 같은 코드태그는 기타 이슈 추적 도구를 사용하는 편을 권합니다. TODO와 같은 코드 태그를 사용하면 VSC의 익스텐션을 사용하여 태그가 달린 코드를 쉽게 검색하고 관리할 수 있습니다.
```
def calculate_area(radius):
    return 3.14159 * radius * radius  # TODO: 최적화 필요
```
```
def calculate_area(radius):
    return 3.14159 * radius * radius  # TODO: 최적화 필요
```
매직 주석은 코드의 실행 환경을 나타냅니다. 단, 3.x 버전에서는 더 이상 사용되지 않습니다. 특수한 경우 사용해주세요.
```
# -*- coding: utf-8 -*-
```
```
# -*- coding: utf-8 -*-
```

매직 넘버 사용 피하기: 매직 넘버(Magic Number)는 소스 코드 내에서 직접적으로 표현된 숫자값을 의미합니다. 이런 숫자들은 일반적으로 코드의 의미를 직관적으로 이해하기 어렵게 만들고, 유지보수를 더 복잡하게 할 수 있습니다. 코드 내에서 직접 숫자를 사용하는 대신, 의미 있는 상수를 사용합니다.
따옴표 사용: 일관된 따옴표 사용을 유지합니다. 파이썬에서는 단일 따옴표(')와 이중 따옴표(")를 모두 사용할 수 있지만, 일관성을 위해 하나를 선택하여 일관되게 사용하는 것이 좋습니다. 저희 회사는 홑따옴표를 사용하며 Black 포매터는 쌍따옴표를 사용합니다. 따라서 이런 것들에 대한 조율이 미리 되어 있어야 합니다.

3. 에러 처리

예외 처리를 통해 예상치 못한 에러에 대비합니다. try-except 블록을 사용하여 오류 상황을 적절히 처리하고, 필요한 경우 사용자에게 명확한 메시지를 제공합니다. 다만 이러한 에러를 대비할 때 너무 많은 코드 블록을 try로 모두 감싸지는 마세요. 디버깅이 어렵습니다. 애러가 났을 경우에는 애러가 난 곳을 명확하게 파악할 수 있어야 합니다.

4. 코드 포매팅 도구 사용

코드 포매팅 도구를 사용하여 코드 스타일을 일관되게 유지할 수 있습니다. 예를 들어, Black, flake8, pylint와 같은 도구가 있습니다. Black 포메터를 일반적으로 많이 사용합니다. 다만 이 포메터가 너무 강제적이어서 일부러 사용하지 않는 곳도 있습니다.