[Tips] VSCode에서 자동으로 'Doxygen' 주석(comment) 달기.

Extension의 무한한 확장성

마이크로소프트의 Visual Studio Code는 사실, 엄밀히 말해서 IDE라기 보다는 Text Editor에 가깝습니다.

(왜냐하면 Visual Studio가 마이크로소프트의 전통적인 IDE이기 때문이죠.)

하지만 수 많은 Extensions(확장팩)들 덕분에 우리들이 단순한 텍스트 편집기가 아닌 IDE로써 활용할 수 있는 것이죠.

C/C++, Python 등, 텍스트 편집기를 IDE로 만들어주는 다양한 컴파일러들은 마이크로소프트에서 기본적으로 제공해줍니다.

이 뿐만 아니라 VSCode를 사용할 때 성능을 극대화시킬 수 있는 응용 프로그램 개념의 Extension들도 제공합니다.

이러한 많은 Extension들 중, 코드를 작성할 때 comment(주석)를 자동으로 달아주는 매우 유용한 Extension인 "Doxygen Documentation Generator" 소개시켜 드립니다.

 

주석(comment)은 혼자 일해도 필요하다.

프로그래밍에서 주석은 필수불가결한 요소라고 생각합니다.

물론! 훌륭한 프로그래머라면 주석을 사용하지 않아도 명시적으로, 그리고 객관적으로 코드를 설계하겠죠.

 

또한 개인 임베디드 프로젝트를 진행할 때 철저히 저 혼자만 작업을 하게 되더라도 주석은 필수입니다.

임베디드 특성상 데이터를 취득하기 위해 다양한 센서들을 사용하게 되는데, 센서의 구동 방식이나 MCU와의 통신 프로토콜 등이 다를 수 있고, rough하게 작성한 코드를 동작 수준에서 확인하고 코드 리뷰를 통해 리펙토링(refactoring) 과정을 거쳐 코드 전문이 수정될 수도 있습니다.

매번 작업하는 순간을 git으로 관리하기도 하지만 주석을 달아놓는 편이 더 편할때도 있습니다.

이런식으로 제 나름대로 각 파일 첫 부분에 제가 해당 파일에 대한 정보를 최대한 간결하게 코멘트로 남겨놓습니다.

또한 조건문에서도 해당 조건의 정의, 그리고 조건이 수행될 때의 결과 등을 적어놓기도 합니다.

특히, 위의 파일은 첫 코드 리뷰는 마치고 아직 리펙토링되지 않은 상태이므로 여러 변수들이나 함수들이 객체화되면 사라지거나 수정될 것입니다.

하지만 적어놔도 항상 마지막에 드는 의문은...

"후에 다른이가 코멘트를 보더라도 내 의도를 쉽게 인지할 수 있을까?"

아니면

"내가 적어놓은 항목들이 과하거나 부족하진 않을까?"

"선배님들이나 시운전팀들이 헷갈리지 않아야 할 텐데.."

등의 찝찝한 생각을 떨쳐낼 수 없었습니다.

 

Doxygen Documentation Generator

Overview

77만회 다운로드에 별이 5개!!

간단하게 소개를 하자면, 아마 VSCode를 사용하고 계시는 많은 분들 중, C/C++ Extension을 설치하신 분들이 많을 겁니다.

그렇다면 RECOMMENDED된 Extension 중에 다음과 같은 Extension을 설치하신 분들도 많을 겁니다.

저는 ROS 프로그래밍을 할 때 80~90% 이상을 모두 C/C++ 언어로 작성했는데, 다른 사람들이 만든 패키지를 검색할 때 이 Doxygen의 주석 형태를 처음 접하게 되었습니다.

VSCode를 사용해 코딩을 하다 보면 잘 모르는 객체나 메소드를 찾아 들어가보면 항상 Doxygen 주석이 달려있어, 처음 접하더라도 객체의 구조나 메소드 사용법을 직관적으로 알 수 있어 매우 도움이 되었습니다.

 

Feature

https://github.com/cschlosser/doxdocgen#features

cschlosser/doxdocgen

정말 수많은 기능들이 있지만, 제가 자주 그리고 유용하게 사용하는 기능들 몇 가지만 소개 해드립니다.

Extension의 설정을 건드리지 않았다면 /**을 입력 후 [Enter]키를 입력하면 자동으로 활성화됩니다.

이 extension을 활성화 시키는 동작을 '트리거링'이라 칭하겠습니다.

그리고 extension 설정 방법은 아래 링크에서 확인 가능합니다.

https://github.com/cschlosser/doxdocgen#config-options

cschlosser/doxdocgen

트리거링 방법을 포함하여 대부분의 기능들을 설정 가능합니다.

저는 이 커스터마이징 부분이 제일 만족스럽습니다.

 

File description

말 그대로 코드의 가장 윗 부분에서 볼 수 있는 기본 설명 입니다.

그냥 파일 가장 윗 부분'즈음'에서 트리거링하면 됩니다.

이 부분은 사용자마다 알맞게 커스터마이징이 필요한 부분일 것입니다.

저는 설정을 바꾸지 않은 디폴트 상태로, 위와 같이 @file, @author, @brief, @version, @date, @copywrite 항목이 자동으로 작성됩니다.

이 항목들은 extension 설정에서 추가 및 수정 가능합니다.

 

Operators / Parameters / Return types / Alignment

함수(혹은 객체나 메소드)에 대한 간단한 설명, 사용된 인수, 반환값이 있다면 반환값에 대한 설명을 적을 수 있습니다.

자동으로 항목들을 분류해서 나타내주는 것이 매우 편리합니다.

순서나 여백 등은 extension 설정에서 수정 가능합니다.

 

Constructors and Destructors

객체의 생성자 및 소멸자에 대한 주석도 자동으로 인식해 달아줍니다.

생성자 위에서 트리거링

소멸자 위에서 트리거링

테스트해보니 기본 생성자(default constructor)도 인식하더군요.

 

Extensive customization

여백을 감싸는 테두리 디자인, 태그 식별 기호 등을 모두 설정에서 수정 가능합니다.

본인의 입맛에 맞게끔 모두 extension 설정에서 커스터마이징 가능합니다.