효율적 개발을 위한 PHP 코딩 가이드라인

범용 규범

  • POSIX Regex 대신 PCRE(Perl-Compatible Regular Expression)을 권장합니다.
  • 편집시 줄바꿈은 LF (ASCII Code 10, 0xA)를 사용합니다.
  • iconv.php와 같은 인코딩 기능을 지원하는 특수 파일을 제외하고 모든 소스 파일(php, txt, xml, html 등)의 인코딩은 Byte Order Mark 없는 UTF-8을 사용합니다.

특수 규범

문자열 escape 처리 지침
  • HTML, XHTML, XML의 모든 attribute value enclosure는 double quotes만을 사용한다.(왜냐하면, PHP 코딩 과정을 단순화하기 위해서입니다. single quotes도 지원하기 위해서는 htmlspecialchars() PHP함수에 ENT_QUOTES를 꼭 추가해 주어야 하기에 과정이나 차후 관리가 복잡해집니다.) 
    <span title="hello"></span>          : YES
    <span title='hello'></span>          : NO!
  • 불필요한 경우에는 escape 처리를 하지 않는다. (escape할 character가 포함되지 않는 constant data 또는 variable value) 
    <span><?php echo $entry['id'];?></span>                                      : YES
    <span><?php echo htmlspecialchars($entry['subject']);?></span>               : YES
    <span><?php echo htmlspecialchars('hello');?></span>                         : NO!
    <span><?php echo htmlspecialchars($entry['id']);?></span>                    : NO!
  • XML(HTML) Element Text 또는 Attribute Value에 JavaScript 문자열의 일부가 아닌 경우는 htmlspecialchars()로 처리한다. 
    <span><?php echo htmlspecialchars($entry['subject']);?></span>                                : YES
    <span title="<?php echo htmlspecialchars($entry['subject']);?>"></span>                       : YES
    <span onclick="alert('<?php echo htmlspecialchars($entry['subject']);?>')"></span>            : NO!
  • XML(HTML) Attribute Value에 JavaScript 문자열의 일부인 경우는 escapeJSInAttribute()로 처리한다. 
    <span onclick="alert('<?php echo escapeJSInAttribute($entry['subject']);?>')"></span>          : YES
    <span onclick="alert(<?php echo escapeJSInAttribute($entry['subject']);?>)"></span>            : NO!
    <span title="<?php echo escapeJSInAttribute($entry['subject']);?>"></span>                     : NO!
  • XML(HTML) CDATA Section Data에 JavaScript 문자열의 일부인 경우는 escapeJSInCData()로 처리한다. 
    <script type="text/javascript>
    //<![CDATA[
    alert("<?php echo escapeJSInCData($entry['subject']);?>");                                              : YES
    alert(<?php echo escapeJSInCData($entry['subject']);?>);                                                : NO!
    alert("<?php echo htmlspecialchars($entry['subject']);?>");                                             : NO!
    alert("<?php echo escapeJSInAttribute($entry['subject']);?>");                                          : NO!
    document.getElementById("span1").title = "<?php echo escapeJSInCData($entry['subject']);?>";            : YES
    document.getElementById("span1").title = "<?php echo escapeJSInAttribute($entry['subject']);?>";        : NO!
    //]]>
    </script>

자바스크립트 사용

텍스트큐브는

  • 자바스크립트가 사용되지 않는 상태에서도 최대한 동작하는 것
  • 점진적 기능 개선(unobstrusive) 방식 : DOM Load 이벤트 핸들러를 이용하여 자바스크립트 기능을 덧붙입니다.

을 원칙으로 합니다.

Textcube 1.8버전부터 jQuery와 EAF가 텍스트큐브 기본 자바스크립트 프레임워크로 사용되지만, 스킨이나 플러그인 제작자들이 선호하는 별도의 라이브러리를 사용할 수 있게 하기 위하여 $ 변수 사용을 피하거나 다음 코딩 방법을 준수하여야 합니다. 

// 호출되지 않았다면 jQuery.noConflict(); 호출
(function($) {
    // $를 사용하는 jQuery 기반 코드
})(jQuery); // anonymous function call을 이용하여 namespace 효과 사용
// 바깥에선 prototype, mootools와 같이 $를 사용하는 다른 라이브러리 코드 그대로 사용 가능

DOM Load 이벤트 핸들러를 여러 구성요소에서 독립적으로 사용할 수 있도록, jQuery(function() { ... }); 및 EAF.addLoadEventListener(function() { ... }); 방식을 사용합니다. EAF도 내부적으로는 jQuery를 이용하므로 서로 충돌하지 않으며 여러 개의 핸들러를 등록할 수 있습니다.

주석

코드 관련 주석의 경우 검색의 용이성을 위하여 다음의 표기를 따릅니다.

  • TOKNOW - 앞으로 알아내야 할 부분
  • TEMPORARY - 임시로 구현한 부분
  • SUGGEST - 이러한 구현으로 제안하는 부분
  • DEPRECATE - 이곳에 있었던 코드는 폐기됨

콜론(:) 앞에 물음표를 붙이면 다른 커미터의 의견을 묻는 내용입니다.

커밋 로그

커밋 로그에는 반드시 ticket 번호를 기술해야합니다. 기술하는 방법은 다음과 같습니다.

  • 커밋이 티켓을 수정하는 경우: fix #nnnn
  • 커밋이 티켓을 참고하는 경우: refs #nnnn
  • 커밋이 티켓을 수정 및 종료하는 경우: close #nnnn

fix, see, close 는 다음과 같이 문맥에 맞추어 쓸 수도 있습니다.

  • fix -> fixed, fixes
  • refs -> references, re, see
  • close -> closed closes

두 개 이상의 티켓에 연관되어 있는 경우 다음과 같이 ","를 사용하여 구분합니다.

  • refs #nnnn, #nnnn, #nnnn ...
  • fixes #nnnn, #nnnn, #nnnn ...
  • closes #nnnn, #nnnn, #nnnn ...

참고로 trac에서 지원하는 위키 문법을 사용하면 timeline을 볼 때 적용되므로, 여러 가지의 변경 사항이 포함된 경우는 unordered list로, 다른 커밋(changeset)을 참조하는 경우는 rNNN 또는 [NNN] 형식의 문법을 사용할 수 있습니다.