소스코드 주석달기

티스토리 메뉴 펼치기 댓글수1

배움/SE

소스코드 주석달기

기차나
댓글수1
해당 소스코드를 '왜' 만들었는 지, '어떻게' 만들었는 지에 대한 정보들은 소스코드에 담겨있어야 한다.

- 주석은 각 코드에 대한 설명이 아니라, '어떠한' 문제를 풀기 위해, 무엇을 하는 지에 대해서 기술되어야 한다.
- 변경에 대한 이력 또한 기술되어야 하는 데, 변경을 유발한 '요구사항'에 대해 기술한다.
- 현재 파일(클래스, 모듈, 함수)를 사용하는 '사용파일'에 대한 이력을 남김을 통해, 현재 파일에 대한 수정 시에 함께 변경이 될 수도 있는 파일(사용파일)에 대한 정보를 확인할 수 있다.
- 생성 사유와 변경 사유에 대한 정보를 찾는 것은 쉬운 일이 아닙니다. 관련 사항을 소스코드에 주석으로 기입함을 통해 '왜' 이렇게 코딩이 되었는 지 그 즉시 파악할 수 있도록 해야합니다.

- 주석 달기는 '코딩' 전에 하는 것이 좋습니다. 코딩 전에 하는 것은 문제를 풀기 위해 사고 하는 단계로 부가적인 일이 아니라고 생각하지만, 코딩 후에 하는 것은 문제를 다 풀고난 후, 혹은 오류를 해결하고 난 후의 일이기 때문에, 또다른 일이 되어버리거든요.

* "index 값을 1증가 시킨다.", "임시 변수에 데이터를 백업한다."처럼 코드를 설명하기 위한 주석은 프로그래밍 언어를 배우는 학생에게나 필요한 것 입니다. 코드의 syntax를 모르는 학생이 이해할 수 잇도록 하는 것일 뿐, syntax를 아는 사람에겐 아무 의미가 없습니다.

파일 주석

  
'/******************************************************************************
' 파일명    : 파일명을 입력
' 작성자    : 작성자 이름을 입력
' 목적      : 파일의 목적을 입력
' 사용방식  : 본 파일을 사용하는 방식을 구체적으로 입력
' 사용파일  : 본 파일을 사용하는 파일의 이름을 입력
' 제한사항  : 본 파일을 사용하는 데 필요한 사항을 입력
' 오류처리  : 본 파일에서 처리한 오류에 대해 입력
' 이력사항
'              YYYY. MM/DD 수정자
'               1. 수정 사유: method_name {, method_name}
'/******************************************************************************


함수 주석


   
'/******************************************************************************
' 함수명    : 함수명을 입력
' 작성자    : 함수 작성자 이름을 입력
' 설명      : 함수 목적에 대한 설명
' 리턴값    : 함수의 반환값을 입력
' 매개변수
'           매개변수명     : 변수 정의를 입력
' Psedo-Code
'           함수 구현에 대한 수도코드를 입력
' Remark
'           함수에 대한 특이 사항을 입력
' 이력사항
'           YYYY. MM/DD 수정자: 변경 날짜 및 수정자의 이름을 입력
'               1. 수정 사유
'/******************************************************************************


파일 내부의 이력 사항은 [파일에 대한 주석], [함수에 대한 주석], [함수 내부의 수정 내용]에 대해 일련의 링크로 볼 수 있다.
[파일 주석-method_name] - [함수 주석-날짜] - [함수 내부 날짜]로 이력사항을 확인할 수 있다.

함수 내부

   
‘YYYY. MM/DD 수정 관련 이력


저는 하나의 함수를 작성하기에 앞서,
주석을 통해 함수 내부에서 처리해야 할 내용과 어떻게 처리할 것인지에 대해 "우선적"으로 기술합니다.

1. 함수명과 리턴값, 매개변수 작성: 함수 뼈대를 작성합니다.
2. 주석 생성: 위의 주석을 그대로 Ctrl + C & Ctrl + V 하고, 설명 및 리턴값을 기술합니다.
3. 주석 내부에 Psedo-Code에 함수에서 처리하고자 하는 문제를 푸는 방식을 간단한 순서도 형식으로 기술합니다.
4. 작성한 Psedo-Code의 내용을 함수 내부로 복사합니다.
5. Psedo-Code의 각 line에 해당 하는 코드를 작성합니다.

물론 Test Driven Development로 수행하고자 한다면, 2번과 3번 사이에 관련 테스트 코드를 작성해서 그 즉시 테스트를 수행할 수 있도록 하는 것이 좋습니다.

위와 같은 순서로 코딩을 하게 된다면, 문제와 알고리즘에 대한 분석이 끝난 후가 되기 때문에, 코딩 중에 발생할 수 있는 문제들에 대해 미리 생각하고 대처할 수 있습니다.
그것도 무려 자연어(한국어, 영어)로 기술된 것을 보면서요.

사용하는 프로그래밍 언어에 따라 조금씩 다르지만, C 혹은 C++과 같이 Pointer를 사용하는 언어의 경우, 그 소스코드를 보고 오류를 찾아내고, 분석해서, 디버깅하는 것은 조금 어렵습니다.
코드를 따라가다보면, 헷갈리기 쉽상이죠.

자연어로 된 것을 풀어나가는 게 더욱 쉽다는 것은 당연한 것!!!

올바른 주석을 달아 쉽게 코딩합시다.^^
관련 태그 목록 #소스코드 #주석 #프로그래밍
맨위로

https://jwoojeong.tistory.com/entry/%EC%86%8C%EC%8A%A4%EC%BD%94%EB%93%9C-%EC%A3%BC%EC%84%9D%EB%8B%AC%EA%B8%B0

신고하기