코딩 표준 (HTML/ASP/JavaScript)

돌아다니다 주운 글인데, 일부는 좀 안맞는 것도 있지만 참고할만한 글인 것 같아서 번역해서 올린다.
http://www.csuchico.edu/web/resources/standards/code.html

코딩 표준 (HTML/ASP/JavaScript)

일반적으로 웹서비스에서는 파일, 테이블, 필드, 변수 네이밍에 첫글자를 소문자로 쓰고 복합단어를 대문자로 구분(e.g., “itemAdd.asp”, “rsStudentList”, “mlHours” 등)하는 헝가리안 표기법을 사용한다.

  • 파일과 폴더 이름
  • 폴더 이름 표준
  • 변수명 (JavaScript, ASP)
  • HTML/ASP 코딩
  • Cascading Style Sheets
  • 자바스크립트
  • SQL formatting
  • SQL 테이블과 필드

파일과 폴더 이름

  1. 모든 폴더는 index.html(혹은 .shtml, .asp)파일을 포함하도록 한다.
  2. 사이트는 논리적, 상속적인 방법으로 조직되어야 한다. 한 디렉토리에 모든 파일을 집어넣는 짓은 하지마라
  3. 모든 파일이름은 소문자라 숫자로 시작한다.
  4. 파일이름에서 숫자가 먼저 나오면 뒤에는 소문자를 쓴다 (e.g., “2editImage.asp”).
  5. 복합 단어는 대문자로 구분한다 (e.g., “itemEdit.asp”).
  6. 밑줄(“_”)이나 대시(“-“)는 파일이름에 사용하지 마세요.
  7. 파일이름에 공백을 사용하지 마세요.
  8. 같은 그룹의 페이지들은 같은 단어나 문자열로 파일이름을 시작한다(e.g., “itemAdd”, “itemAdded”, “itemEdit”, “itemEdited”). 이렇게하면 서로 연관있는 페이지들을 찾기 편하다.
  9. 서버측에서 포함되는 파일(모든 템플릿 기반 파일)에는 .shtml 을 확장자로 사용하고 .htm 이나 .html 을 사용하지 마세요.
  10. 파일이나 폴더이름 시작부분에 사용되는 축약어는 소문자로 표기한다 (e.g., “atecStaffList.asp”, “imcResources.shtml”).

    예시

    좋음: tlpServices.shtml

    나쁨: TLPServices.shtml
    나쁨: tLPServices.shtml
    나쁨: tlp-services.shtml
    나쁨: tlp_services.shtml
    나쁨: tlpServices.htm
    나쁨: tlpservices.shtml

폴더이름 표준

  1. 이미지 파일은 “/images/.” 폴더에 저장하세요.
  2. 이미지가 적은 사이트라면, 이미지 폴더를 루트 폴더 바로 아래에 두고 사이트의 모든 이미지를 그 폴더에 저장하세요.
  3. 이미지가 많고 다단계의 페이지들이 있다면, 사이트의 각 하위 폴더마다 “images” 폴더를 만들어서 각 하위 페이지에서 사용하는 모든 이미지는 각 “images” 폴더에 저장하는게 좋습니다.
  4. 큰 이미지 대신 작은 썸네일을 보여주는 사이트라면 모든 썸네일 이미지를 “images” 폴더 아래의 “thumbnails” 폴더에 저장하세요. 썸네일 이미지의 파일명은 원래 크기의 이미지와 똑같게 하세요.
  5. 포함하는 파일은 루트 디렉토리 아래의 “/_include/” 에 저장하세요.
  6. 자바스크립트 파일은 루트 디렉토리 아래의 “/_scripts/” 에 저장하세요.
  7. CGI 스크립트는 루트 디렉토리 아래의 “/cgi-bin/” 에 저장하거나 스크립트가 사용되는 디렉토리에 저장하세요.
  8. 스타일시트 파일은 루트 디렉토리 아래의 “/_styles/”에 저장하세요.
  9. 새 사이트를 개발하는데 사용되는 파일은 루트 디렉토리 아래의 “/_dev/” 에 저장하세요.

변수명 (JavaScript, ASP)

변수명은 헝가리안 표기법을 따릅니다.

  1. 모든 이름은 소문자로 시작하도록 합니다(숫자는 안됩니다).
  2. 복합 단어 이름은 대문자로 구분하도록 합니다(e.g., “firstName”).
  3. 변수명에 밑줄(“_”)이나 대시(“-“) 를 사용하지 마세요.
  4. 설명이 없거나 심하게 축약된 이름은 피하도록 하세요. 변수가 정확히 무엇을 의미하는지 알 수 있도록 명명하는게 중요합니다(예를 들어, “firstName”을 “fn”으로 쓰지 마세요). “i”나 “x” 같은 이름은 “for” 반복문에만 쓰는게 좋습니다.

HTML/ASP 형식

  1. 실제로 사용되는 페이지는 XHTML Transitional 규격을 만족하도록 해야합니다.
  2. 모든 ASP 코드는 (Response.Write 문 포함) 올바른 XHTML 코드를 만들어내야 합니다.
  3. 모든 ASP 명령과 문장은 첫글자를 대문자로 표기하세요
  4. 모든 접속은 포함되는 파일(inculde file)을 이용하세요.
  5. 대부분의 경우, 레코드 선언은 문서의 제일 위쪽 태그 이전에 위치시키세요.
  6. 모든 레코드셋 이름은 “rs”로 시작합니다 (e.g., “rsItemInfo”).
  7. 접속을 사용하는 모든 페이지는 페이지의 마지막에서 접속을 종료해주세요 (태그 아래).
  8. 모든 질의문은 구분자가 있어야 합니다(e.g., “itemEdit.asp?itemID=33”, 이건 안됨 “itemEdit.asp?33”).
  9. 변수, 레코드셋, 질의 구분자 이름은..
  10. 소문자로 시작합니다
  11. 변수 내에서의 단어 구분은 대문자를 이용합니다 (e.g., “userFirstName”)
  12. 밑줄은 사용하지 않습니다
  13. 축약어가 첫글자부터 쓰이면 축약어 전체를 소문자로 표기합니다 (e.g., “sqlString,” 이건 안됨 “sQLString”).
  14. 매우 짧은 구문을 제외한 모든 구문은 어떤 목적으로 작성되었는지 설명하는 주석을 달아두어야 합니다.
  15. 여러줄에 걸친 구문은 코드와 분리하는 묶음기호를 이용해서 명확히 작성하도록 합니다.
    < %
    If aspStatement Then
    ?
    ?
    End If
    %>
    

Cascading Style Sheets

  1. 스타일 이름은 모두 소문자로 하세요 (XHTML에선 대문자가 허용되지 않습니다), 밑줄(“_”)도 안됩니다.
  2. 포맷팅을 위한 스타일은 배타적으로 사용하세요 (모든 <font>태그는 제거되어야 합니다).
  3. 기존의 HTML 요소를 적극 활용하세요. h1 태그로 필요한 스타일을 만들 수 있는데도 .head1 클래스를 추가하지 마세요.
  4. 이미 있는 스타일시트를 활용하세요. 정말로 필요할 경우가 아니라면 새 스타일을 만들지 마세요. 링크의 스타일은 전체에 적용하세요.
  5. 스타일 시트의 스타일을 알파벳순으로 정렬해놓으면 유지보수 측면에서 좋습니다.
  6. 특정 페이지에만 사용하는 스타일은 페이지 헤더에서 정의해주세요.

자바스크립트

  1. 정확한 동작을 위해서 모든 script태그는 type 과 language 를 포함해야 합니다. language=”JavaScript” type=”text/JavaScript”. 를 사용하세요.
  2. JavaScript 변수는 ASP 변수 네이밍 규약을 따릅니다.
  3. 작성된 자바스크립트 (한페이지에서만 사용되는)는 사용될 페이지의 헤더에 위치시키세요.
  4. 여러 페이지에서 사용될 함수는 .js 파일로 만드세요. 우리의 표준에서는 .js 파일을 root/_scripts/ 폴더에 저장합니다.
  5. 자주 사용하는 함수도 자바스크립트 파일에 모아놓을 수 있습니다. 이 파일들은 절대경로로 참조하세요.

SQL 형식

  1. 모든 SQL 예약어는 대문자로 입력합니다 (e.g., SELECT * FROM tableName WHERE dtStartDate > ‘3/3/03’).
  2. 여러 테이블을 쿼리할때는 JOIN 문을 이용하세요. 비표준 다중 테이블 쿼리는 자제해주세요.

SQL 테이블과 필드

  1. 테이블과 필드 이름은…
    1. 소문자로 시작합니다.
    2. 변수명 내에서의 구분은 대문자를 이용하도록 합니다 (e.g., “userFirstName”).
    3. 밑줄(“_”)은 사용하지 않습니다.
    4. 축약어가 처음에 사용되면 소문자로 표기합니다 (e.g., “sqlString”, 이건 안됨 “sQLString”)
  2. 같은 그룹의 테이블들은 같은 문자열로 시작하도록 합니다 (e.g., “mlHours”, “mlPlatform”, “mlService”).
  3. 테이블 이름에 복수형은 사용하지 않습니다.
  4. 테이블 이름과 필드 이름에 숫자는 사용하지 않습니다.
  5. 필드 이름의 첫문자를 자료형으로 표기하세요.
    1. 문자열 자료형은 (char, varChar, etc.) “s” 로 시작합니다(e.g. “sFirstName”).
    2. 정수 자료형은 “i”로 시작하되 (e.g., “iFacilityID”), 주키(primary key)로 사용되는 필드라면 “ID”로 명명합니다.
    3. 실수형은 “n” (for “numeric”) 으로 시작합니다.
    4. 날짜형은 “dt” 로 시작합니다.
    5. 비트형은 “b” 로 시작합니다.
  6. 모든 테이블은 “ID”라는 이름의 주키(primary key) 필드를 가지고 있어야 합니다. 다중 테이블 쿼리에서 필드가 테이블 이름과 함께 구분(e.g., “userList.ID”)되므로 테이블 이름과 같이 명명하지 마세요 (e.g., “ID,” 이건 안됨 “userListID”).
  7. 뷰와 스토어드 프로시저는 “view”와 “proc” 로 시작해서 테이블과 구분짓습니다 (e.g., “viewCurrentStaff,” “procCalcDaysLeft”).
    1. 저도 이부분에 대해 고민을 좀 해보았는데요.
      우선 dash(-) 는 사용못하는 언어가 많은 것 같아서
      포팅이나 혹은 제3언어와의 통합에서 이득을 볼 것 같구요.
      PHP 나 ASP 내에서는 대문자로만 이루어진 상수 전용으로
      밑줄을 사용하려는 의도 같습니다.
      또한 함수명으로 밑줄을 자주 사용하는 PHP의 경우,
      변수에는 밑줄을 사용하지 않는 것이 더욱 가독성이 좋아 보이네요.

      꾸벅~!

Leave a Reply