소스 코드 주석 스타일 지정 팁 및 모범 사례
대규모 프로젝트에 시간을 할애 한 개발자는 코드 주석의 중요성을 이해합니다. 동일한 애플리케이션에 많은 기능을 구현할 때 상황이 복잡 해지는 경향이 있습니다. 함수, 변수 참조, 반환 값, 매개 변수를 포함하여 많은 데이터 비트가 있습니다 ... 어떻게 계속 할 것으로 예상됩니까??
솔로 및 팀 프로젝트 모두에서 코드를 주석하는 것이 필수적입니다. 그러나 많은 개발자는이 프로세스를 수행하는 방법을 알지 못합니다. 나는 내 자신의 트릭을 깔끔하고 형식화 된 코드 주석 작성. 표준 및 코멘트 템플릿은 개발자마다 다를 수 있지만 궁극적으로는 깨끗하고 읽기 쉬운 코멘트 코드의 혼란스러운 부분을 자세히 설명합니다..
주석 형식화의 차이점에 대해 논의하기 시작해야합니다. 이렇게하면 프로젝트 코드로 얼마나 자세하게 자세를 취할 수 있는지 더 잘 알 수 있습니다. 이후에는 즉시 사용할 수있는 몇 가지 구체적인 팁과 예제를 제공 할 것입니다.!
코멘트 스타일 : 개요
제시된 이러한 아이디어는 단지 지침 청결한 논평으로. 개별 프로그래밍 언어는 설명서 설정 방법에 대한 지침이나 사양을 명시하지 않습니다..
즉, 현대 개발자들은 함께 그룹화하여 자신의 코드 주석 시스템을 형식화합니다. 나는 몇 가지 주류 스타일을 제안하고 그들의 목적을 자세하게 설명 할 것이다..
인라인 주석 처리
실질적으로 모든 단일 프로그래밍 언어가 제공합니다. 인라인 코멘트. 이는 한 줄짜리 내용으로 제한되며 특정 시점 이후에만 텍스트에 주석을 답니다. 예를 들어 C / C ++에서 다음과 같이 인라인 주석을 시작합니다.
// 변수 목록 시작 var myvar = 1; ...
이것은 몇 초 동안 코드에 chiming하는 데 적합합니다. 아마도 혼란스러운 기능을 설명한다.. 많은 매개 변수 또는 함수 호출로 작업하는 경우 인라인 주석을 주변에 배치 할 수 있습니다. 그러나 가장 유익한 용도는 작은 기능에 대한 단순한 설명.
if (callAjax ($ params)) // 사용자 매개 변수를 사용하여 callAjax를 성공적으로 실행 ... 코드
위의 모든 코드는 여는 대괄호 뒤에 새 행에 있어야합니다. 그렇지 않으면 모두 동일한 주석 행에 걸리게됩니다.! 선외로 나가는 것을 피하십시오 일반적으로 한 줄 주석을 페이지 아래로 끝까지 볼 필요는 없지만 특히 코드의 혼란을 막기 위해 마지막 순간에 훨씬 쉽게 끝낼 수 있습니다.
기술 블록
큰 설명을 포함 할 필요가있을 때 일반적으로 단일 라이너가 트릭을하지 않습니다. 프로그래밍의 모든 영역에서 사전 형식의 주석 템플릿이 사용됩니다.. 설명 블록 함수 및 라이브러리 파일에서 가장 많이 볼 수 있습니다. 새 기능을 설정할 때마다 선언 위에 설명적인 블록을 추가한다..
/ ** * @desc는 메시지를 표시하는 모달 창을 엽니 다. * @param string $ msg - 표시 할 메시지 * @return bool - 성공 또는 실패 * / function modalPopup ($ msg) ...
위의 설명은 간단한 설명의 예입니다. JavaScript로 아마 함수를 작성했습니다. 모달 팝업 단일 매개 변수를 사용합니다. 위의 주석에서 phpDocumentor와 비슷한 구문을 사용했습니다. 각 구문 앞에는 @ 기호 다음에 선택된 키가옵니다. 이것들은 어떤 식 으로든 코드에 영향을 미치지 않으므로 다음과 같이 작성할 수 있습니다. @기술 대신에 @desc 변화가 전혀 없다..
이 작은 키는 실제로 호출됩니다. 댓글 태그 이는 웹 사이트에 많이 기록되어 있습니다. 자신 만의 것을 만들어서 코드 전체에서 원하는대로 사용할 수 있습니다. 나는 그들이 모든 것을 너무 흐리게하는 것을 도울 것을 찾는다. 중요한 정보를 한눈에 확인할 수 있습니다.. 당신은 또한 내가 / * * / 블록 스타일 주석 형식. 이것은 모든 것을 유지할 것이다. 훨씬 더 깨끗한 각 줄에서 이중 슬래시를 시작하는 것보다.
그룹 / 클래스 설명
함수 및 루프를 주석 처리하는 것 외에도 블록 영역은 자주 사용되지 않습니다. 당신이 정말로 필요로하는 곳 댓글 차단 백엔드 문서 또는 라이브러리 파일의 머리 부분에 있습니다. 모든 것을 진행하고 웹 사이트의 모든 파일에 대한 견고한 문서를 작성하는 것은 쉽습니다. WordPress와 같은 많은 CMS에서이 방법을 볼 수 있습니다..
페이지의 맨 위에는 파일 자체에 대한 주석이 있어야합니다. 이 방법으로 편집중인 곳을 빠르게 확인하십시오. 동시에 여러 페이지에서 작업 할 때. 또한이 영역을 다음과 같이 사용할 수 있습니다. 가장 중요한 기능을위한 데이터베이스 교실 밖.
/ ** * @desc이 클래스는 사용자 상호 작용을위한 함수를 포함합니다. * 예 : user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / abstract class myWebClass
위조품에 대한 작은 샘플 수업을 사용했음을 알 수 있습니다. myWebClass 암호. 메타 정보를 추가했습니다. 연락처에 대한 내 이름과 이메일 주소. 개발자가 오픈 소스 코드를 작성할 때 일반적으로 좋은 연습이므로 다른 사람들이 지원을 요청할 수 있습니다. 대규모 개발 팀에서 일할 때도 확실한 방법입니다..
태그 @required 내가 다른 곳에서 사용한 것을 본 적이 없다. 필자는 많은 프로젝트를 커스터마이징 한 페이지에서만 몇 가지 프로젝트의 형식을 유지했습니다. 파일에 페이지를 포함시킬 때마다 코드를 출력하기 전에 페이지를 가져와야합니다. 따라서 이러한 세부 정보를 기본 클래스 주석 블록에 추가하는 것이 좋은 방법입니다. 어떤 파일이 필요한지 기억하십시오..
프런트 엔드 코드 주석 처리
이제 3 가지 중요한 설명 템플릿에 대해 살펴 보았습니다. 몇 가지 다른 예를 살펴 보겠습니다. 정적 HTML에서 jQuery 및 CSS 코드로 이동 한 많은 프론트 엔드 개발자가 있습니다. HTML 주석은 프로그래밍 응용 프로그램과 비교하여 목적이 명확하지 않지만 스타일 라이브러리 및 페이지 스크립트를 작성할 때 시간이지나면서 지저분해질 수 있습니다.
자바 스크립트는 Java, PHP 및 C / C와 유사한 주석 처리 방식을 사용합니다.++. CSS는 슬래시와 별표로 구분 된 블록 스타일 주석 만 사용합니다. CSS 나 JS는 서버 측에서 파싱되지 않기 때문에 방문자에게 공개적으로 주석이 표시된다는 것을 명심해야합니다. 그러나이 두 가지 방법 중 하나는 코드에 유익한 정보를 다시 남겨 두는 데 유용합니다.
특히 CSS 파일을 분리하는 것은 어려움이 될 수 있습니다. 우리 모두는 Internet Explorer 나 Safari에 대한 수정 사항을 설명하기 위해 인라인 코멘트를 남기는 데 익숙합니다. 하지만 나는 CSS 주석을 jQuery와 PHP 수준에서 사용할 수 있다고 생각한다. 코드 주석 작성을위한 몇 가지 팁을 살펴보기 전에 스타일 그룹을 만드는 방법을 알아 봅시다..
CSS 스타일 그룹
CSS를 수년간 디자인해온 사람들에게는 거의 제 2의 성격이 있습니다. 모든 속성, 구문을 천천히 외운 다음 스타일 시트를위한 자체 시스템을 구축하십시오. 내 자신의 일을 통해 나는 내가 부른 것을 창조했다. 그룹화 유사한 CSS 블록을 한 영역으로 묶는 방법.
CSS를 편집하기 위해 돌아 가면 몇 초 만에 필요한 것을 쉽게 찾을 수 있습니다. 스타일을 그룹화하는 방식은 전적으로 귀하에게 달려 있으며이 시스템의 장점입니다. 아래에 요약 한 몇 가지 기본 표준이 있습니다.
- @resets - 기본 브라우저 여백, 채우기, 글꼴, 색상 등을 제거합니다..
- @fonts - 단락, 표제, 인용구, 링크, 코드
- @navigation - 주요 핵심 웹 사이트 탐색 링크
- @layout - 래퍼, 컨테이너, 사이드 바
- @header & @footer - 디자인에 따라 다를 수 있습니다. 가능한 스타일에는 링크 및 정렬되지 않은 목록, 꼬리말 열, 제목, 하위 네비게이션
스타일 시트를 그룹화 할 때 태깅 시스템 많은 도움이 될 수 있습니다. 그러나 PHP 나 JavaScript와는 달리 @그룹 태그 다음에 카테고리가 나옵니다. 아래 2 가지 예를 포함하여 내가 의미하는 바를 느낄 수 있습니다..
/ ** @group footer * / #footer styles ...
/ ** @group 바닥 글, 작은 글꼴, 열, 외부 링크 ** /
또는 각 주석 블록에 약간의 추가 세부 사항을 추가 할 수 있습니다. 나는 선택한다. 일을 간단하고 간단하게하라. 스타일 시트는 쉽게 훑어 볼 수 있습니다. 주석 처리는 문서 작성에 대한 모든 내용을 담고 있습니다.!
더 나은 코멘트 스타일링을위한 4 가지 팁
이 기사의 전반부에서는 코드 주석 작성을위한 다양한 형식을 살펴 보았습니다. 이제 코드를 깨끗하고 체계적이며 이해하기 쉽게 유지하는 데 도움이되는 전반적인 팁을 살펴 보겠습니다..
1. 모든 것을 읽을 수있게하십시오.
때때로 개발자로서 우리는 그것을 잊어 버립니다. 우리는 인간이 읽을 수 있도록 의견을 쓰고 있습니다.. 우리가 이해하는 모든 프로그래밍 언어는 기계 용으로 제작되었으므로 일반 텍스트로 변환하는 것이 지루할 수 있습니다. 여기서 우리는 대학 수준의 연구 논문을 쓰는 것이 아니라 그냥 팁 남기기.!
function getTheMail () // 사용자 정의 sendMyMail () 함수 호출이 true를 반환하면 // 여기에 코드가 전자 메일을 작성합니다. * /libs/mailer.class.php에서 sendMyMail ()을 찾습니다. 사용자가 모든 필드를 채우는 지 확인합니다 메시지가 전송됩니다! * / if (sendMyMail ()) return true; // true로 유지하고 화면에 성공을 표시
심지어 몇 단어 만 있습니다. 아무것도없는 것보다는 낫다. 나중에 프로젝트를 편집하고 작업 할 때 잊어 버릴 일이 많다는 것은 놀라운 일입니다. 동일한 변수와 함수 이름을 매일 보지 않으므로 코드의 대부분을 천천히 잊어 버리는 경향이 있습니다. 따라서 너무 많은 의견을 남기지 말라.! 하지만 너무 많은 나쁜 댓글을 남길 수 있습니다..
일반적으로 엄지 손가락으로, 글을 쓰기 전에 잠시 쉬는 시간을 가져라.. 자신에게 물어 프로그램에 대해 가장 혼란스러운 것은 무엇인가? 과 어떻게 설명 할 수 있니? “더미” 언어? 또한 고려하십시오 왜 당신이 코드를 쓰는 거지?.
맞춤 제작 (또는 제 3 자) 기능의 목적을 잊었을 때 가장 혼란스러운 오류가 나타납니다.. 몇 가지 다른 파일로 이어지는 덧글 흔적을 남겨주세요. 이 기능을 사용하면 더 쉽게 기능을 기억할 수 있습니다..
2. 약간의 공간을 완화 시키십시오.!
얼마나 중요한지 충분히 강조하지 못한다. 공백 될 수 있습니다. 이것은 간다. 이중으로 진실하다 수백 개의 파일이있는 거대한 웹 사이트에서 작업하는 PHP 및 Ruby 개발자를위한 것입니다. 하루 종일이 코드를 쳐다볼 것입니다! 중요한 영역으로 건너 뛸 수 있다면 좋지 않을까요??
$ dir1 = "/ home /"; // 기본 홈 디렉토리 설정 $ myCurrentDir = getCurDirr (); // 현재 사용자 디렉토리를 설정합니다. $ userVar = $ get_username (); // 현재 사용자의 사용자 이름
위 예제에서 각 행의 주석과 코드 사이에 여분의 패딩이 있음을 알 수 있습니다. 파일을 스크롤하면서이 스타일의 주석을 달았습니다. 분명하게 두드러진다.. 그것 오류를 찾고 수백 배나 쉽게 코드를 수정합니다. 가변 블록이 그렇게되면 깨끗한.
어떻게 작동하는지 혼동하는 함수 내부의 코드에서 비슷한 작업을 수행 할 수 있지만,이 메서드는 결국 인라인 주석으로 코드를 복잡하게 만들 것이며, 이는 순서와 정반대입니다! 이 시나리오에서 권장합니다. 논리 영역 주변에 커다란 블록 행 주석 추가.
pageload에서 하위 탐색 숨기기 / ** 기본 앵커에서 click 이벤트를 확인합니다 .itm div 기본 링크를 방지합니다. $ (document) .ready (function () $. 작업을 클릭하면 페이지가 변경되지 않습니다. .itm의 부모 요소에 액세스하여 다음 .sub 목록을 열고 열기 / 닫기 ** / $ ( '. itm a') .to ( 'click', function (e ) .) e.preventDefault (); $ (this) .parent (). next ( '. sub'). slideToggle ( 'fast');););
이것은 하위 메뉴 슬라이딩 탐색을 대상으로하는 jQuery 코드의 작은 비트입니다. 첫 번째 의견은 왜 우리가 모든 것을 숨기고 있는지를 설명하기 위해 인라인입니다. .보결 수업. 실시간 클릭 이벤트 처리기 위에 블록 주석을 사용하고 모든 글쓰기를 같은 지점으로 들여 쓰기. 이것은 실전 단락보다는 일을 더 편하게 만듭니다 - 특히 다른 사람들이 귀하의 의견을 읽는 경우.
3. 코딩 중 코멘트
적절한 간격과 함께 이것은 들어갈 수있는 최선의 습관 중 하나 일 수 있습니다. 아무도 일을하고 각 부분을 문서화 한 후에 프로그램으로 돌아가고 싶지 않습니다. 우리 대부분은 돌아가서 혼란스러운 부분을 문서화하고 싶지 않습니다! 정말 많은 일을합니다..
그러나 코딩하는 동안 주석을 쓸 수 있다면 모든 것이 여전히 마음 속에 새롭다.. 일반적으로 개발자는 문제에 매달리고 가장 쉬운 해결책을 찾기 위해 웹을 조사합니다. 당신이 유레카의 순간을 치고 그런 문제를 해결할 때, 이전의 실수를 이해할 수있는 명확한 순간이 있습니다. 이것은 가장 좋은 시간 코드에 대한 솔직한 의견을 남기려면.
또한이 방법을 사용하면 모든 파일에 주석을다는 데 익숙해집니다. 돌아가고 어떻게 작동하는지 파악하는 데 필요한 시간은 이미 함수를 작성한 후에 훨씬 더 커집니다.. 미래의 자기 팀원과 팀 동료 모두 미리 코멘트를 남겨 주셔서 감사합니다..
4. Buggy 오류 다루기
우리는 모두 코드를 작성하는 데 몇 시간 동안 컴퓨터 앞에 앉을 수는 없습니다. 나는 우리가 시도 할 수 있다고 생각하지만, 어느 시점에서 우리는 잠을 자야한다! 일부 기능이 여전히 중단 된 상태에서 코드를 사용하여 코드를 작성해야 할 가능성이 높습니다. 이 시나리오에서는 당신이 일을 떠난 곳에 대한 길고 자세한 설명을 남기십시오..
신선한 밤잠을 자고 난 후에도 코딩의 스윙으로 되돌아 가려면 얼마나 어려울 지 놀라실 수 있습니다. 예를 들어 이미지 업로드 페이지를 작성하고 완료하지 않은 상태로 두어야하는 경우 진행 과정에서 중단 한 부분에 대해 의견을 제시해야합니다.. 이미지가 업로드되고 임시 메모리에 저장됩니까? 또는 업로드 양식에서 인식되지 않거나 업로드 후 페이지에 제대로 표시되지 않을 수 있습니다..
댓글 달기는 두 가지 주된 이유로 중요합니다. 먼저 네가 그만 뒀던 곳에서 쉽게 데려다 준다. 과 마음에 새롭게 다시 시도하여 문제를 해결하십시오.. 둘째로 웹 사이트의 라이브 프로덕션 버전과 테스트 근거를 구별합니다.. 주석은 다음을 위해 사용되어야 함을 기억하십시오. 왜 네가 뭔가하고 있는지 설명해., 정확히 무엇을하지 않는가?.
결론
웹 앱과 소프트웨어 개발은 어렵지만 성취감있는 실행입니다. 당신이 진정으로 소프트웨어를 만드는 것을 이해하는 소수의 개발자 중 한사람이라면 코딩 기술로 성숙하는 것이 중요합니다.. 설명 적 설명을 남기는 것은 장기적으로는 좋은 습관 일뿐입니다., 너는 결코 그것을 후회하지 않을 것이다.!
명확한 코드 주석 달기에 대한 제안이 있으면 아래의 토론 영역에서 알려주십시오.!
