라이믹스/매뉴얼/코딩 규칙

상위 문서: 라이믹스/매뉴얼

1. 개요#

라이믹스 코어에 기여할 때 적용하는 공식 코딩 규칙을 정리한 문서이다. 실제 변경 대상의 .editorconfig와 기존 코드도 함께 확인한다. 공식 규칙이 별도로 정하지 않은 부분은 PSR-1·PSR-12를 따른다.

2. 파일과 들여쓰기#

• 문자 인코딩은 BOM 없는 UTF-8, 줄바꿈은 LF를 사용한다.
• 기본 들여쓰기는 탭 하나이다. Markdown·YAML 등 공백을 사용하는 파일은 기존 형식을 유지한다.
• 들여쓰기 목적으로 탭과 공백을 섞지 않는다.
• PHP만 들어 있는 파일은 끝의 ?>를 생략한다.
• EditorConfig를 지원하는 편집기에서는 프로젝트의 설정을 활용한다.

3. 괄호와 공백#

PHP의 클래스·함수·조건문·반복문은 여는 중괄호를 다음 줄에 둔다. 명령이 하나여도 중괄호를 사용한다.

if ($enabled)
{
    $result = getResult($id, $options);
}

함수명과 호출 괄호 사이에는 공백을 넣지 않고, 인자를 나누는 쉼표 뒤에는 한 칸을 둔다. 비교 연산자 양쪽에도 공백을 둔다. if 같은 키워드 뒤에는 한 칸을 권장하지만 XE 시절 코드 주변에서는 기존 스타일을 유지할 수 있다.

클로저는 같은 줄에 중괄호를 둘 수 있으며, JavaScript도 언어 특성에 맞게 같은 줄의 중괄호를 허용한다.

$double = function($value) { return $value * 2; };

여러 줄의 PHP 배열은 마지막 항목 뒤에도 쉼표를 남긴다. JSON에는 마지막 쉼표를 쓰지 않는다. 공식 코딩 규칙은 JavaScript 배열에도 마지막 쉼표를 남기지 않는 방식을 안내한다.

4. 주석과 PHPDoc#

주석은 관련 코드나 조건문 바로 위에 둔다. 원칙적으로 영어의 완전한 문장을 사용하며, 클래스와 함수에는 /**로 시작하는 PHPDoc 주석을 붙인다. 파라미터와 반환값을 실제 코드와 일치시킨다.

/**
 * Return the number of items.
 *
 * @return int
 */
public function getCount(): int
{
    return $this->_count;
}

이 예제의 $_count 속성은 해당 클래스에 선언되어 있다고 가정한다.

5. 가시성과 타입#

새 클래스 메서드는 가시성·파라미터 타입·반환 타입을 명시한다. public이 아닌 메서드와 속성의 이름은 원칙적으로 언더바로 시작한다. 하위 호환성 때문에 엄격한 선언을 할 수 없는 경우는 예외이다.

코어가 지원하는 모든 PHP 버전에서 실행할 수 있어야 한다. 개발자 PC의 PHP에서만 동작하는 문법을 무조건 도입하지 않는다. 특정 버전에만 존재하는 기능은 호환성 검사와 대체 동작을 마련한다. 문자열·정수 비교에는 가능하면 ===를 사용하고, 타입 변환이 필요하면 의도를 명시한다.

네임스페이스 안에서 전역 상수를 참조할 때는 \RX_CLIENT_IP처럼 전역임을 드러내는 표기를 사용한다.

6. 커밋과 PR#

커밋 메시지는 가능하면 영어의 동사원형으로 시작하는 명령형으로 쓴다. 한국어도 가능하며 변경 위치와 동작을 구체적으로 설명한다.

Fix thumbnail generation for missing images
회원정보 수정 시 오류 메시지 표시 개선

‘함수 개선’처럼 무엇이 달라지는지 알 수 없는 제목은 피한다. PR과 관계없는 스타일 수정은 별도 변경으로 나눈다. 라이믹스/매뉴얼/GitHub 이슈 및 PR 작성도 참고한다.

7. 오류·의존성과 프론트엔드#

• 기본 오류 설정에서 notice·deprecated를 포함한 오류가 발생하지 않도록 한다.
• 라이브러리 버전은 코어의 지원 PHP 범위와 맞춘다. 의존성을 갱신할 때는 대상 브랜치의 설치·배포 절차도 확인한다.
• CSS·JS는 사용자가 수정할 수 있는 원본 형태를 제공한다. 공개 원본이 있는 외부 라이브러리의 압축본은 공식 규칙의 예외에 해당한다.
• 공식 문서의 과거 버전 예시는 현재 지원 범위와 구분하여 읽는다.

8. 같이 보기#

• 라이믹스/매뉴얼/설치 환경
• 라이믹스/매뉴얼/GitHub 이슈 및 PR 작성

9. 출처#

이 문서는 라이믹스 공식 매뉴얼을 바탕으로 설명과 예제를 정리하였다. 공식 매뉴얼은 CC BY-SA 4.0으로 배포된다. 원문의 기여 이력은 rhymix-docs 저장소에서 확인할 수 있다.