소스코드 정리 - 주석

학부생 프로그래밍 수업에서 교수님이 강조하는 것 중에 하나는 소스코드에 주석을 남기는 것이다.

 

그 당시에는 기껏해야 50라인의 C언어 코드를 작성하면서 주석을 남기는 게 너무 거추장 스럽다고 생각했지만 지금에 와서 주석을 남기는 것은 매우 중요하다는 것을 깨닫는다.

 

개발을 하면서 거의 대부분을 기능을 라이브러리를 끌어다 쓰는 경우가 많다보니, 여러 라이브러리를 사용하게 되고 자연 스럽게 라인이 길어지다니보니, 여러 라이브러리를 혼용하여 사용하는 파일을 보게 되면 여러 가지로 이해하기 어려운 상황이 오게된다.

 

그렇기에 주석을 남기고 그때의 상황을 메모해두는 것이 중요한 것 같다.

 

주석에는 양식이 정해진 것은 없겠지만, 약속을 하면서 쓰는 것이 중요할 것 같고, 간결하게 설명을 하더라도, 남겨두는 편이 좋은 것 같다.

 

대다수의 프로그래밍 언어는 멀티라인 주석을 남길 수 있으니 꼭 남기는게 좋겠다.

 

양식은 자유지만 내가 생각하는 양식은 다음과 같은데

 

파일 상단에 남기는 설명문

title: 

author:

date:

description:

파일 상단에 남기는 설명문은 파일에 있는 여러 코드나 기능들을 포괄적으로 설명하며, 어느 파일에서 참조하여 쓰이는지도 남기면 디버깅 시 유용하게 쓰일 것 같다.

author부분은 여러명이서 작성할 때, 최초 작성자를 알수 있게 하며, 파일에 수정 사항이 생길 때 마다, author, date, description을 남기면 change log도 남길 수 있다.

 

 

함수에 남기는 주석

description: 

param: 

return: 

함수 같은 경우에는 매개변수와 반환 값 그리고 함수의 설명 및 주의 사항을 남긴다.

매개변수에는 주로 옵션값으로 오는 값이나, 필수 여부, 그리고 예시 값을 남긴다면 어떤 역할을 할 때, 어떤 값이 쓰이는 지 유추해보면서 디버깅을 할 수 있다.

리턴값에는 반환하는 값으나 객체의 형태에 대한 설명과 어디에서 쓰이는지와 무엇에 쓰이는지 정도로 남긴다.

설명으로는 주의사항이나 구현 시 어려웠던 부분을 남긴다면, 추후 기능 수정이나 오류 수정에 참조할 수 있다.

 

 

라인에 남기는 주석

사실 라인에 남기는 주석은 그 기준이 사람마다 다를 수도 있을 것 같다. 누구에게나 당연한 부분에 대한 라인과 그렇지 않고 설명이 필요한 라인인지를 구분하는 것은 어려울 수 있다.

사실 함수의 매우 로직을 간결하게 작성한다면 주석을 최소화하여 사용할 수 있지만, 개발의 과정에 있어서 현실적인 상황에서 언제나 모든 코드를 간결하게 작성하기란 쉽지 않기 때문에 그런 부분이 있다면 라인에 주석을 남겨두는 것이다.

그러면 추후 리펙토링에도 도움이 된다.