-
Notifications
You must be signed in to change notification settings - Fork 55
codingGuideline
- 줄바꿈 문자는
LF(ASCII Code 10,0xA)를 사용합니다. - 들여쓰기(indent)는 Tab 문자를 사용합니다. 단, Python 코드가 사용될 경우엔 PEP-8 규칙에 따라 공백 4칸을 기준으로 합니다.
- 코드를 작성할 때, 하나의 명령어(statement)는 문장(sentence)으로, 논리적으로 하나의 완결된 의미를 가지는 덩어리(statements)는 문단(paragraph)로 생각하여, 문단 사이에는 빈 줄을 하나씩 넣어 가독성을 높입니다.
- 코드가 그 자체로 중급 프로그래머가 '왜', '어떻게'를 온전히 이해할 수 있을 정도로 단순한 경우를 제외하고는 주석을 붙입니다. (아래의 주석 작성 방법 참조)
- 변수명을 지을 때는 다음과 같은 방식을 따릅니다.
- 클래스 및 데이터, 오브젝트를 담는 변수는 단순 명사/고유명사 또는 형용사 + 명사 형태 (예:
notificationData,globalSettings) - 어떤 동작을 지원하기 위한 경우라도 이것을 인간화(
-er,-or등의 어미를 붙이는 것)하여 짓습니다. - 복수 개의 데이터를 담는 변수(배열 등)들은 복수형 또는
List와 같은 말을 붙여 구분합니다. 단, Map이나 dictionary 형태의 데이터는 key가 일종의 속성 이름처럼 사용될 때는 복수형을 쓰지 않아도 됩니다. - 조건 갈래를 판단하기 위한 boolean 변수는 is + 동사의 수동형 또는 is + 형용사 형태 (예:
is_sorted,is_acceptable) - 가독성을 위해 is는 생략할 수 있음. - 함수는 1인칭 단수 현재형 동사 또는 동사 + 목적어 형태
- 텍스트큐브는 코드의 방대함, 다양한 공헌자들 고유의 스타일 및 역사성 때문에 변수 이름 짓기 규칙을 일괄적으로 강제하지는 않지만, 각 프로그래밍 언어의 주요 커뮤니티에서 사용되는 관습을 존중하되, 대체로 CamelCase를 따릅니다.
- 클래스 이름은 첫 글자도 대문자로, 함수나 변수명은 첫 글자를 소문자로 합니다.
- 하나의 함수 내에서만 사용되는 지역 변수의 경우 CamelCase 대신 소문자와 밑줄문자를 섞어쓰는 방식을 이용해도 무방합니다.
- 어떤 경우라도 한 이름 내의 단어들이 명확히 구분되어 인식될 수 있으면 됩니다.
- PHP : Zend Framework Naming Conventions
- Python : PEP-8 Style Guide for Python Code
- 클래스 및 데이터, 오브젝트를 담는 변수는 단순 명사/고유명사 또는 형용사 + 명사 형태 (예:
- POSIX Regex 대신 PCRE(Perl-Compatible Regular Expression)을 권장합니다.
- iconv.php와 같은 인코딩 기능을 지원하는 특수 파일을 제외하고 모든 소스 파일(php, txt, xml, html 등)의 인코딩은 Byte Order Mark 없는 UTF-8을 사용합니다.
-
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를 이용하므로 서로 충돌하지 않으며 여러 개의 핸들러를 등록할 수 있습니다.
- 코드가 역사성을 가질 때(매우 특수한 경우에만 일어나는 예외에 대한 처리 등) 관련해서 처음 리포팅한 사람의 이름이나 닉네임 또는 관련 있는 티켓 번호를 주석에 포함시킵니다.
- 대략 40~50줄이 넘어가는 함수들은 최소한 summary라도 반드시 적습니다.
- 3개 이상의 여러 and, or 조건이 뭉쳐있는 조건식의 경우 그 의미를 써줍니다. (2개는 권장, 3개 이상은 의무)
-
영어를 기본으로 하되, 복잡하고 긴 내용의 경우 이해를 돕기 위해 한국어를 사용합니다.
-
주석의 종류는 다음과 같이 구분합니다. 가독성을 기준으로 개발자가 알맞게 선택하여 사용합니다.
-
inline : 한 줄 내에서 앞쪽에는 코드가 있고 그 뒷쪽에 주석이 붙는 형태입니다. 코드 끝과 주석 표시 문자 사이에 최소 2칸의 공백 또는 하나 이상의 탭 문자를 둡니다.
-
single-line : 주석으로만 이루어진 한 줄짜리 주석입니다. 보통
for,while,if등 큰 덩어리의 코드를 포함하는 블록 구문 앞이나 논리적으로 코드가 문단으로 구분될 때 오게 되며 대부분 다음의 코드 덩어리가 무엇을 하는지 설명하기 위한 경우가 많기 때문에 주어를 생략할 때는 동사를 3인칭 단수 현재형으로 작성합니다. 그렇지 않으면 전체 문장 구조를 지킵니다. -
multi-line : 아래와 같은 형식으로 편집합니다. vi 등 텍스트 편집기에서 제공하는 text wrapping 기능(textwidth 지정 후 단축키
gq)을 이용하면 좋고, 수동으로 할 경우 문장이 끝나는 마침표 뒤에는 2칸의 공백을 사용하여 가독성을 높입니다./*
- First line
- ...
- Last line */
-
-
파일, 클래스, 함수에 대한 주석은 PHP Documentor 스타일을 따릅니다.
코드 관련 주석의 경우 검색의 용이성을 위하여 다음의 표기를 따릅니다.
- TOKNOW - 앞으로 알아내야 할 부분
- TEMPORARY - 임시로 구현한 부분
- SUGGEST - 이러한 구현으로 제안하는 부분
- DEPRECATE - 이곳에 있는 코드는 곧 폐기될 예정임
- OBSOLETE - 이곳에 있었던 코드는 폐기됨 (사용하면 오류 발생, 보통은 코드에서 제거되고 문서에만 남은 상태여야 함) 콜론(:) 앞에 물음표를 붙이면 다른 커미터의 의견을 묻는 내용입니다.
커밋 로그에는 반드시 ticket 번호를 기술해야합니다. 기술하는 방법은 다음과 같습니다.
- 커밋이 티켓을 수정하는 경우:
fix #nnnn - 커밋이 티켓을 참고하는 경우:
refs #nnnn - 커밋이 티켓을 수정 및 종료하는 경우:
close #nnnnfix, see, close 는 다음과 같이 문맥에 맞추어 쓸 수도 있습니다. fix -> fixed, fixesrefs -> 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]형식의 문법을 사용할 수 있습니다.
- Source | Wiki Front | Main | Notice