코드 스타일 가이드

이 가이드는 BeeWare에 대한 코드 작성을 위한 정보와 지침을 포함합니다.

코드 스타일

BeeWare는 코드베이스에서 PEP 8을 따르지만, 줄 길이는 79자에서 88자로 확장됩니다. 가능한 경우 Ruff를 사용하여 PEP 8 규약을 강제 적용합니다. 코드를 커밋할 때 pre-commit이 Ruff를 포함한 검사를 실행합니다. 가능한 경우 코드를 자동 포맷팅하여 당사의 포맷팅 및 스타일 기준을 충족하도록 합니다. 일부 IDE에서는 저장 시 자동으로 Ruff를 실행하도록 설정할 수 있어 이 과정에 도움이 됩니다.

PEP 8에서 가장 중요한 부분은 섹션 0: 어리석은 일관성은 소인배의 악마이다임을 명심하십시오. PEP 8과 일관성을 유지하는 것이 합리적이지 않은 상황이 존재하며, 해당 규칙에 부합하지 않는 코드를 작성하는 것이 허용될 뿐만 아니라 때로는 바람직하다는 점을 이해하는 것이 중요합니다. 대부분의 상황에서 일관성을 유지하는 것만큼이나 언제 규칙을 어겨야 하는지 아는 것이 중요합니다.

이러한 점의 한 가지 예는 명명 규칙에서 찾아볼 수 있습니다. BeeWare 라이브러리는 종종 다른 언어와 연동해야 할 필요가 있습니다. 다른 언어를 위한 래퍼를 구축할 때는 파이썬의 규칙보다는 대상 언어의 명명 규칙을 따르는 것이 바람직하며(경우에 따라서는 필수적입니다). 예를 들어, 자바 코드를 호출하거나 참조할 때는 함수 이름에 PEP 8에서 권장하는 mixedCase 대신 자바에서 선호하는 snake_case 형식을 사용해야 합니다.

API 명명, 변수 등에 대해 미국식 철자를 따릅니다.

또한 PEP 8에는 BeeWare에 특화된 몇 가지 추가 사항이 있습니다:

긴 함수 호출 분할하기

인수가 두 개 이상인 함수 호출이 한 줄에 다 들어가지 않을 경우, 각 인수를 별도의 줄에 배치하고 마지막 인수의 뒤에는 쉼표를 붙이십시오. Ruff는 여러 인수를 한 줄에 줄바꿈하여 배치하는 형식을 허용하며(그리고 이를 권장합니다):

my_function(
    arg1, arg2, arg3
)

이 방식은 사용하지 마십시오. 대신, 마지막 인자에 쉼표를 추가하여 인자들을 한 줄에 하나씩 나열하십시오:

my_function(
    arg1,
    arg2,
    arg3,
)

긴 문자열 분할

문자열 인수를 줄 길이 제한을 충족하기 위해 여러 줄로 나누어야 할 경우, 연결된 문자열 리터럴을 괄호로 묶어 해당 문자열이 단일 인수임을 명확히 표시해야 합니다. 즉, 다음과 같은 형식을 권장합니다:

my_function(
    (
        "this is a very long string "
        "that is wrapped over two lines"
    ),
    second_argument,
)

번역:

my_function(
    "this is a very long string "
    "that is wrapped over two lines",
    second_argument,
)

피해야 할 것들

우리는 utils 모듈을 가능한 한 피하려고 노력하지만, 때로는 피할 수 없다는 점을 이해하고 있습니다. 선호하는 대안은 utils 모듈을 사용하는 대신 해당 기능을 소스 코드의 다른 곳에서 구현할 수 있는 장소를 찾는 것입니다.

일반적으로 앱 시작 속도를 높이기 위해 비용이 많이 드는 초기화 코드는 피하거나 연기합니다. 예를 들어, toga-core 패키지의 모듈들은 "지연 로드"됩니다. 즉, 모든 모듈을 미리 불러오는 대신 요청이 있을 때만 불러옵니다. 이렇게 하면 시작 속도가 빨라지고, 앱이 실제로 사용하는 부분에만 시간을 투자하게 됩니다.