[Python] 명명규칙 - 파이썬 코드 스타일 가이드

요즘 Python 코드를 작성하면서, 계속 PEP8 경고가 뜨는 걸 보고 찾아봤습니다.

명명규칙 이라든지, 개발 스타일이 파이썬의 규칙에 맞지 않다는 겁니다.

Java 에 익숙해져 있어서, 잘 몰랐는데 익숙해져야 겠네요.

---

PEP ( Python Enhancement Proposal )는 Python의 발전에 기여한 수 많은 개발자들이 제안한 내용을 문서화한 내용입니다. 그 내용에 대한 책임자(?)도 있는 모양입니다. ( 문서란에 저자가 있네요. ) 일단 적용된 내용은 절대 변경되지 않는다고 합니다. ( once assigned are never changed )

https://www.python.org/dev/peps/

PEP 0 -- Index of Python Enhancement Proposals (PEPs)

---

어찌되었든 알아야 할 것은 개발 시 스타일 가이드가 있고, Python 개발 시 그것을 지켜야 한다는 겁니다. ( 뭐.. 예외적인 상황이 발생할 경우는 어쩔 수 없겠죠. )

https://www.python.org/dev/peps/pep-0008/

PEP 8 -- Style Guide for Python Code

---

네이밍 가이드

b (single lowercase letter) 단일 소문자

B (single uppercase letter) 단일 대문자

lowercase 소문자

lower_case_with_underscores 밑줄을 포함하는 소문자

UPPERCASE 대문자

UPPER_CASE_WITH_UNDERSCORES 밑줄을 포함하는 대문자

CapitalizedWords (CapWords 또는 CamelCase -- 글자의 울퉁불퉁한 모양 때문에 그런 이름이 붙었다.). 때때로 StudlyCaps라고도 한다.

참고: CapWord에서 약어를 사용할 때는 약어의 모든 글자를 대문자로 써라. 그래서 HTTPServerError가 HttpServerError보다 낫다.

mixedCase (첫문자가 소문자로 CapitalizedWords와 다르다)

밑줄을 포함하는 CapitalizedWords(추하다!)

서로 관련된 이름을 그룹화하기 위해 짧은 고유 접두사를 사용하는 스타일도 있다. 이 스타일은 파이썬에서 많이 사용되지 않지만, 완전성을 위해 언급한다. 
예를 들어, os.start() 함수는 전통적으로 st_mode, st_size, st_mtime 등의 이름의 항목을 갖는 'tuple'을 반환한다. 
(이것은 구조체를 호출하는 POSIX 시스템의 필드와 대응을 강조하기 위해서인데, 이것에 익숙한 프로그래머에게 도움을 준다.)

X11 라이브러리는 모든 공개 함수명에 'X'를 접두어로 사용한다. 파이썬에서 이 스타일은 일반적으로 불필요하다고 여겨지는데, 객체가 속성과 메서드 이름의 접두어이고 모듈이 함수명의 접두어이기 때문이다.

덧붙여, 선행 또는 후행 밑줄을 사용하는 다음의 특별한 형태도 사용된다 (이것은 일반적으로 모든 규칙과 함께 조합될 수 있다):

• _single_leading_underscore : 약한 "내부용" 표시기이다. 예를 들어, from M import *는 밑줄로 시작하는 이름을 갖는 객체를 가져오지 않는다.

• single_trailing_underscore_ : 관습에 의해 파이썬 키워드와 충돌을 피하기 위해 사용된다. 예를 들어, Tkinter.Toplevel(master, class_='ClassName')

• __double_leading_underscore : 클래스 속성의 이름을 지을 때, name mangling을 호출한다 ( 클래스 FooBar 안에서, _boo는 _FooBar_boo가 된다; 아래를 보라).

• __double_leading_and_trailing_underscore__ : "매직" 객체 또는 사용자 제어 이름공간에 살아있는 속성. 예를 들어, __init__, __import__, 또는 __file__. 결코 이런 이름을 만들지 마라; 그저 문서에 적힌 대로 쓰기만 해라.

 

명명규칙

1. 피해야 할 이름들 "l"(소문자 엘), "O"(대문자 오), "I"(대문자 아이)는 단일 문자 변수명으로 결코 쓰지마라.
어떤 글꼴에서 이 문자들은 숫자 1 그리고 0과 구별되지 않는다. "l"을 쓰고 싶을 때는 대신 "L을 사용하라.

1. 패키지와 모듈 이름
모듈은 짧은 소문자로만 구성된 이름을 가져야 한다. 가독성을 개선할 수 있다면 밑줄을 사용할 수 있다. 파이썬 패키지 또한 짧고 소문자로만 구성된 이름을 가져야 한다. 비록 밑줄의 사용은 찬성하지 않지만.

1. C또는 C로 쓰여진 확장 모듈이 고수준 (예를 들어, 좀더 객체지향적인) 인터페이스를 동반할 때, C/C 모듈은 선행 밑줄을 가져야 한다.

1. 클래스이름
클래스 이름은 일반적으로 CapWord 관례를 따른다.
인터페이스가 문서화되고 주로 호출가능으로 사용되는 경우에는 함수에 대한 명명 협약이 대신 사용될 수 있다.

내장(함수?) 이름에는 별도의 협약에 있음에 주의하라: 대부분의 내장(함수?) 이름은 단일 단어(또는 함께 실행되는 2개 단어)이며, 단지 예외 이름과 내장 상수들에만 사용되는 CapWord 협약이 있다.

1. 자료형 변수 이름
PEP 484에서 도입된 자료형 변수의 이름은 보통 CapWord를 선호하는 짧은 이름을 사용한다: T, AnyStr, Num. 공변 또는 대응하는 반공변 거동을 정의하려고 사용된 변수에는 접미사 _co 또는 _contra를 붙일 것을 권장한다. 

예:

from typing import TypeVar

VT_co = TypeVar('VT_co', covariant=True)
KT_contra = TypeVar('KT_contra', contravariant=True)

예외 이름

예외는 클래스가 될 수 있기 때문에, 클래스 이름 협약이 여기에 적용된다. 하지만, 예외 이름에 접미사 "Error"를 사용해라(만약 예외가 실제로 오류라면).

(이 변수들은 단지 한 모듈 내에서만 사용하기로 정해져 있기를 희망한다.) 함수들에 적용되는 것과 동일한 협약을 따른다.
* 형태로 사용이 설계된 모듈은 전역 변수들을 내보내는 것을 막기 위해 all 메카니즘을 사용하거나, 그러한 전역변수들의 이름에 선행 밑줄을 넣는 더 오랜된 협약을 사용할 것이다.

함수 이름

함수명은 소문자이어야 하고 가독성 개선이란 필요에 의해 단어들을 밑줄로 분리하여야 한다.

mixedCase는 하위 버전과의 호환성을 유지하기 위해, 이미 널리 사용된 스타일(예를 들어 threading.py)의 컨텍스트에서만 허용된다.

함수와 메서드 인자
인스턴스 메서드의 첫번째 인자는 항상 'self'를 사용하라.

클래스 메서드의 첫번째 인자는 항상 'cls'를 사용하라.

만약 함수의 인자명이 예약어와 충돌한다면, 약어나 철자 줄이기보다는 단일 후행 밑줄을 덧붙이는 것이 일반적으로 더 낫다. 그래서 class_가 clss보다 낫다. (아마 더 나은 방법은 동의어를 사용해서 그런 충돌을 피하는 것이다.)

메서드 이름과 인스턴스 변수

함수 명명 규칙을 사용하라: 가독성 개선의 필요에 따라 소문자 단어들을 밑줄로 분리한다.

비공개 메서드와 인스턴스 변수에만 하나의 선행 밑줄을 사용하라.

서브클래스와 이름 충돌을 피하기 위해, 두개의 선행 밑줄을 사용하여 파이썬의 이름 변환 규칙을 호출하라.

파이썬은 이런 이름들을 클래스명으로 변환한다: 만약 클래스 Foo가 __a 라는 이름의 속성을 가지고 있다면, Foo.__a로 접근할 수 없다. (Foo._Foo__a를 호출함으로써 강제적으로 접근할 수는 있다.) 
일반적으로, 이중 선행 밑줄은 서브클래스로 설계된 클래스 안에 속성과 이름 충돌을 피할 목적으로만 사용해야 한다.

주의: __names의 사용에 대한 논란이 있다.

상수

상수는 보통 모듈 수준에서 정의되고 밑줄로 분리된 대문자 단어로 쓰여진다. 
예: MAX_OVERFLOW, TOTAL.

상속을 위한 설계
항상 클래스의 메서드와 인스턴스 변수(통칭: "속성")가 공개인지 비공개인지를 결정하라. 
만약 의심이 든다면, 비공개를 선택하라; 나중에 공개 속성을 비공개로 만드는 것보다 비공개를 공개로 만드는 것이 더 쉽다.

공개 속성은 해당 클래스와 무관한 클라이언트가 사용할 것으로 예측되는 속성으로, 하위 비호환 변화를 피하도록 약속되어야 한다. 비공개 속성은 제삼자 파티에 의해 사용될 것으로 예상되지 않는 속성이다; 
비공개 속성이 변경되지 않거나 심지어 제거되지 않을 거란 보장을 할 수 없다.

이 지침에서 "private"란 항목을 사용하지 않는다. 파이썬에는 실제로 'private'한 속성이 없기 때문이다 (일반적으로 불필요한 작업 없이).

또다른 범주의 속성은 'subclass API' (다른 언어에서는 종종 'protected'라고 불린다)의 일부가 되는 속성이다. 어떤 클래스는 상속을 통해 그 클래스의 기능을 확장하거나 수정하여 사용하도록 설계된다. 
그런 클래스를 설계할 때, 어떤 속성이 공개이고 어떤 속성이 subclass API인지, 그리고 어떤 속성이 진짜로 기본 클래서에서만 사용되는지 명확한 판단을 하는데 주의해야 한다.

---

한글 번역

https://kongdols-room.tistory.com/18

PEP8 한글 번역 - 파이썬 기초(0)

https://kenial.tistory.com/902

PEP-0008 파이썬 코드 스타일 가이드(Style Guide for Python Code) 한글 번역

https://wikidocs.net/book/1079

내가 파이썬을 배우는 방법