[IT/개발] [MSDN] 코딩기술 - 주석(comment)

코딩 기술에는 소프트웨어 개발의 여러 가지 측면이 통합되어 있습니다. 일반적으로 코딩 기술은 응용 프로그램의 기능에 영향을 미치지는 않지만, 소스 코드의 가독성을 향상시키는 데 기여합니다. 여기서는 프로그래밍, 스크립팅, 태그 및 쿼리 언어와 같은 모든 형식의 언어가 고려됩니다.

여기에서 정의된 코딩 기술은 고정된 집합의 코딩 표준을 구성하는 데는 사용하지 않는 것이 좋습니다. 그보다는 특정 소프트웨어 프로젝트에 사용되는 코딩 표준을 개발하기 위한 지침으로 사용하는 것이 좋습니다.

코딩 기술은 다음 세 단원으로 구분됩니다.

• 이름
• 주석
• 서식

이름

명명 스키마는 응용 프로그램의 논리적 흐름을 이해할 수 있는 가장 강력한 수단 중의 하나입니다. 이름에는 "어떻게"보다는 "무엇을"이 나타나야 합니다. 내부 구현을 노출시키는 이름을 사용하지 않으면 복잡성이 줄어든 추상화 계층을 유지할 수 있습니다. 예를 들어, GetNextArrayElement() 대신 GetNextStudent()를 사용할 수 있습니다.

올바른 이름을 선택하는 것이 어렵다는 것은 사용자가 항목의 목적을 더 정확하게 분석하고 정의할 필요가 있다는 것을 의미할 수 있습니다. 이름의 길이는 정확한 의미를 전달할 수 있을 정도로 길어야 하지만 너무 길어져서 의미가 모호해지면 안됩니다. 프로그램 상에서 고유 이름은 특정 항목과 다른 항목을 구분하는 용도로만 사용되며, 표현 이름의 기능은 사용자의 이해를 돕는 것입니다. 따라서 사용자가 이해할 수 있는 이름을 제공하는 것이 좋습니다. 하지만 선택된 이름은 해당 언어의 규칙과 표준을 준수해야 합니다.

다음은 명명 기술에서 권장되는 사항입니다.

루틴

• 루틴 이름 AnalyzeThis()와 변수 이름 xxK8과 같이 주관적으로 해석될 수 있는 모호한 이름은 사용하지 않습니다. 이와 같은 이름은 추상화에 기여하기 보다 모호함의 원인이 됩니다.
• 개체 지향 언어에서 클래스 속성 이름에 Book.BookTitle과 같은 클래스 이름을 포함시키는 것은 불필요합니다. 그 대신 Book.Title을 사용합니다.
• 지정 개체에서 특정 동작을 수행하는 루틴을 명명하기 위해서는 CalculateInvoiceTotal()와 같은 동사-명사 방식을 사용합니다.
• 함수 오버로딩이 허용되는 언어에서 모든 오버로드는 유사한 동작을 수행해야 합니다. 함수 오버로딩이 허용되지 않는 언어에서는 유사한 기능을 관련시켜 주는 명명 표준을 설정합니다.

변수

• 해당하는 변수 이름의 끝에 Avg, Sum, Min, Max, Index와 같은 계산 한정자를 추가합니다.
• 변수 이름에 min/max, begin/end 및 open/close와 같은 보완적인 쌍을 사용합니다.
• 대부분의 이름은 연속되는 몇 개의 단어로 구성되므로, 대소문자를 혼용하여 쉽게 읽을 수 있도록 합니다. 또한 변수와 루틴을 쉽게 구별하기 위해 루틴 이름에는 각 단어의 첫 글자가 대문자로 시작되는 파스칼 대/소문자(CalculateInvoiceTotal)를 사용합니다. 변수 이름에는 첫 단어를 제외한 각 단어의 첫 글자가 대문자로 시작하는 카멜 대/소문자(documentFormatType)를 사용합니다.
• 부울 변수 이름에는 fileIsFound와 같이 Is가 포함되어야 합니다. Is는 Yes/No 또는 True/False 값을 내포합니다.
• 상태 변수를 명명하는 경우에는 Flag와 같은 구문을 사용하지 않습니다. 이 구문은 두 개 이상의 값을 가질 수 있다는 점에서 부울 변수와 다릅니다. documentFlag를 사용하는 대신 documentFormatType와 같이 더 정확한 이름을 사용합니다.
• 단 몇 줄의 코드에서만 사용되는 임시 변수에 대해서도 의미 있는 변수를 사용하십시오. i 또는 j와 같은 단일 글자 변수 이름은 단기 루프 인덱스에만 사용합니다.
• For i = 1 To 7과 같은 리터럴 숫자나 리터럴 문자열은 사용하지 않습니다. 그 대신 For i = 1 To NUM_DAYS_IN_WEEK와 같은 명명된 상수를 사용하여 관리와 이해를 쉽게 합니다.

테이블

• 테이블을 명명하는 경우에는 이름을 단수로 표현합니다. 예를 들어, Employees 대신 Employee를 사용합니다.
• 테이블 열을 명명하는 경우에는 테이블 이름을 반복하지 않습니다. 예를 들어, Employee라는 테이블에서 EmployeeLastName이라는 필드를 사용하지 않습니다.
• 열 이름에 데이터 형식을 포함시키지 않습니다. 이렇게 하면 나중에 데이터 형식을 변경할 때 필요한 작업의 양이 줄어들게 됩니다.

Microsoft SQL Server

• 저장 프로시저 앞에 sp를 붙이지 마십시오. sp는 시스템 저장 프로시저를 식별하기 위해 예약된 접두사입니다.
• 사용자 정의 함수 앞에 fn_을 붙이지 마십시오. fn_은 기본 제공 함수를 식별하기 위해 예약된 접두사입니다.
• 확장 저장 프로시저 앞에 xp_를 붙이지 마십시오. xp_는 시스템 확장 저장 프로시저를 식별하기 위해 예약된 접두사입니다.

기타

• 가능하면 약어를 사용하지 않습니다. 다만 사용자가 일관성 있게 만든 약어는 사용합니다. 약어에는 단 한 가지 의미만 존재해야 하며, 각 약자에는 단 하나의 약어가 존재해야 합니다. 예를 들어, minimum의 약어로 min을 사용하는 경우 다른 곳에서 minute의 약자로 min을 사용해서는 안됩니다.
• 함수를 명명하는 경우 GetCurrentWindowName()과 같이 반환되는 값에 대한 설명을 포함시킵니다.
• 프로시저 이름과 마찬가지로 파일과 폴더 이름도 그 용도를 정확하게 나타내야 합니다.
• ProcessSales()라는 루틴과 iProcessSales라는 변수와 같이 서로 다른 요소를 위해 이름을 반복 사용하지 않습니다.
• 코드 검사 시 혼동을 방지하려면 요소를 명명할 때 write 및 right와 같은 동음 이의어를 사용하지 않습니다.
• 요소를 명명하는 경우 철자가 자주 틀리는 단어를 사용하지 않습니다. 또한 color/colour 및 check/cheque와 같이 지역마다 철자가 다르다는 점도 알아 둡니다.
• 데이터 형식을 식별하기 위해 입력 마크(예: 문자의 $, 정수의 %)를 사용하지 않습니다.

주석

소프트웨어 설명서는 외부와 내부 설명서의 두 가지 형태로 존재합니다. 사양, 도움말 파일 및 디자인 문서와 같은 외부 설명서는 소스 코드의 외부에서 관리되며, 내부 설명서는 개발자가 개발 시에 소스 코드 내부에서 작성한 주석들로 구성됩니다.

외부 설명서를 사용할 수도 있지만, 하드 카피 설명서를 잊어 버릴 수 있으므로 소스 코드 목록을 독자적으로 유지해야 합니다. 외부 설명서는 사양, 디자인 문서, 변경 요청, 버그 목록 및 사용되는 코딩 표준으로 구성되어야 합니다.

내부 소프트웨어 설명서의 한 가지 문제는 소스 코드와 일치하도록 주석을 관리하고 업데이트하는 것입니다. 적절한 주석이 추가된 소스 코드는 실행 시에 특별한 역할을 하지 않지만, 상당히 복잡하고 귀찮은 소프트웨어를 관리해야 하는 개발자에게 있어서는 상당히 중요한 역할을 합니다.

다음은 주석 추가 시 권장되는 사항입니다.

• C#에서 개발을 수행하는 경우 XML 문서 기능을 사용합니다. 자세한 내용은 XML 문서를 참조하십시오.
• 코드를 수정하는 경우에는 반드시 최신 주석을 코드에 추가하십시오.
• 모든 루틴의 시작부에는 이 루틴의 목적, 전제, 제한 등을 나타내는 정확한 표준 주석을 추가하는 것이 도움이 됩니다. 정확한 주석은 이 루틴의 용도와 목적을 간략하게 설명할 수 있어야 합니다.
• 코드 줄의 끝에 주석을 추가하지 않습니다. 끝부분에 주석이 있으면 코드를 읽기가 더 어렵습니다. 하지만 변수 선언에 대해 주석을 추가하는 경우에는 줄 끝에 주석을 추가하는 것이 좋습니다. 이 때 탭을 사용하여 모든 주석을 일렬로 정렬합니다.
• 모든 줄에 별표가 사용된 혼란스러운 주석을 사용하지 않습니다. 그 대신 공백을 사용하여 주석과 코드를 구분합니다.
• 입력 프레임을 사용하여 블록 주석을 둘러싸지 않습니다. 이렇게 하면 멋지게 보일 수는 있지만 관리가 어려워집니다.
• 나중에 관리 작업을 수행하는 동안 혼동을 방지하려면 임시 주석이나 관련이 없는 주석을 완전히 제거한 후에 배포합니다.
• 복잡한 코드 부분을 설명하는 주석이 필요한 경우 그 코드를 검사하여 이 주석을 다시 작성해야 하는지를 결정합니다. 가능하면 오류 코드를 제공하지 말고 다시 작성합니다. 일반적으로 코드를 단순하게 만든다고 해서 성능이 저하되는 것은 아니지만, 성능과 유지 관리성 사이에 균형을 유지해야 합니다.
• 주석을 작성하는 경우 완벽한 구문을 사용하십시오. 주석은 코드를 모호하게 하는 것이 아니라 명확하게 하는 것입니다.
• 나중에 따로 주석을 추가할 시간이 없으므로 코딩과 주석 작업을 동시에 수행하십시오. 또한 자신이 작성했던 코드를 다시 살펴보아야 합니다. 지금은 코드가 명확하게 이해되지만 6주 후에는 명확하지 않을 수도 있습니다.
• 유머스러운 말과 같은 불필요하고 부적절한 주석을 사용하지 않습니다.
• 주석을 사용하여 코드의 목적을 설명하십시오. 주석은 코드를 그대로 옮겨 놓은 것이 아닙니다.
• 코드에서 쉽게 알아볼 수 없는 모든 내용을 주석에 추가합니다.
• 반복되는 문제를 해결하려면 버그 수정과 작업 코드에 대해 주석을 사용합니다.
• 루프와 논리 분기로 이루어진 코드에 대해 주석을 사용합니다. 이 주석은 소스 코드 사용자에게 도움이 되는 중요한 부분입니다.
• 응용 프로그램 전체에서 일관적인 문장 부호와 구조로 일정한 스타일을 사용하여 주석을 작성합니다.
• 공백을 사용하여 주석 구분 기호와 주석을 분리합니다. 이렇게 하면 색 표시를 사용하지 않고 코드를 보는 경우에도 쉽고 명확하게 주석을 볼 수 있습니다.

서식

서식은 코드의 논리적 구조를 명확하게 합니다. 소스 코드의 서식을 일관적이고 논리적인 방식으로 적용하면 자신이나 다른 개발자가 이 소스 코드를 해독하는 데 도움이 됩니다.

다음은 서식 기술에서 권장되는 사항입니다.

• 들여쓰기의 표준 크기(예: 공백 4개)를 설정하고 이 크기를 일관적으로 사용합니다. 지정된 들여쓰기를 사용하여 코드부를 정렬합니다.
• 하드 카피 형태로 소스 코드를 출판하려면 한 가지 글꼴을 사용합니다.
• 중괄호 쌍이 함께 나타나는 경우에는 다음과 같이 여는 중괄호와 닫는 중괄호를 수직으로 정렬합니다.

  for (i = 0; i < 100; i++)
  {
     ...
  }

  여는 중괄호가 줄의 끝에 나타나고 닫는 중괄호가 줄의 앞에 나타나는 경우에는 다음과 같은 스타일을 사용할 수 있습니다.

  for (i = 0; i < 100; i++){
     ...
  }

  선택된 스타일을 소스 코드 전체에서 일관적으로 사용합니다.

• 논리적 구조에 따라 코드를 들여쓰기합니다. 들여쓰기를 사용하지 않으면 다음과 같이 코드를 이해하기가 어렵습니다.

  If ... Then
  If ... Then
  ...
  Else
  End If
  Else
  ...
  End If

  코드를 들여쓰면 다음과 같이 코드를 쉽게 이해할 수 있습니다.

  If ... Then
     If ... Then
     ...
     Else
     ...
     End If
  Else
  ...
  End If

• 소스 코드 편집기의 스크롤을 방지하고 하드 카피가 명확하게 표시되도록 하기 위해 주석과 코드의 최대 줄 길이를 설정합니다.
• 코드의 목적이 변경되지 않는 범위 내에서 모든 연산자의 전후에 공백을 사용합니다. 예를 들어, 한 가지 예외로는 C++에서 사용되는 포인터 표기법이 있습니다.
• 공백을 사용하여 소스 코드의 구조를 체계적으로 표시할 수 있습니다. 이렇게 하면 코드 "단락"을 만들 수 있으므로, 사용자는 소프트웨어의 논리적 구조를 쉽게 이해할 수 있습니다.
• 하나의 코드가 여러 줄에 걸쳐 나타나는 경우, 다음 줄이 없으면 코드가 불완전하다는 사실을 명확히 하기 위해 연결 연산자를 각 줄의 끝에 추가합니다.
• 한 줄에 두 개 이상의 문을 사용하지 않습니다. 한 가지 예외로는 C, C++, C# 또는 JScript 에서 사용되는 for (i = 0; i < 100; i++)와 같은 루프가 있습니다.
• HTML을 작성하는 경우 태그와 특성의 표준 서식을 설정합니다. 예를 들어 태그는 모두 대문자로 설정하고 특성은 모두 소문자로 설정할 수 있습니다. 다른 방법으로는 XHTML 사양을 사용하여 모든 HTML 문서가 유효하도록 보장할 수 있습니다. 웹 페이지를 만드는 경우 파일의 크기가 문제될 수 있지만, 따옴표 붙은 특성값과 닫는 태그를 사용하면 쉽게 관리할 수 있습니다.
• SQL 문을 작성하는 경우 모든 키워드에는 대문자를 사용하고 테이블, 열 및 뷰와 같은 데이터베이스 요소에는 대소문자를 혼용합니다.
• 실제 파일 사이에서 소스 코드를 논리적으로 분할합니다.
• 다음과 같이 각각의 주 SQL 절을 별도의 줄에서 작성하면 쉽게 코드를 읽고 편집할 수 있습니다.

  SELECT FirstName, LastName
  FROM Customers
  WHERE State = 'WA'

• 길고 복잡한 코드부는 쉽게 이해할 수 있는 작은 모듈로 분할합니다