좋은 주석이란

안녕하세요 여러분! 일단고 팀입니다.

벌써 크리스마스가 기다려지는 시기네요.

모두 감기 조심하세요.

 

 

오늘 이야기 할 주제는 개발할 때 ‘좋은 주석이란 무엇인가’입니다.

주석은 코딩을 할 때 코드의 내용을 메모하는 목적으로 쓰이며 협업할 때 코드의 이해를 높이는 등 유용하게 쓰이죠. 이러한 주석은 코드의 의도를 명확히할 때 좋은 작용이 되지만, 혼란을 야기하는 좋지 않은 작용을 일으킬 때도 있습니다. 그래서 좋은 주석이란 무엇인가에 대해 이야기를 해보고자 합니다.

 

좋은 주석 달기

1. 코드를 의도를 명확히 설명하는 주석 (혼란을 없애는 주석)
   • 변수 명 자체만으로 어떤 목적을 가진 변수인지 알 수 있으면 가장 좋지만, 라이브러리 등에 종속되어 이름을 변경하지 못하는 등의 상황에는 주석을 활용하면 좋습니다.
   • 또한 주석의 내용을 너무 축약하여 다른 사람이 보았을 때 이해하지 못하는 상황이 발생한다면 잘못된 해석을 유발하여 혼란이 생길 수 있다. 따라서 개인이 혼자 알고있는 용어는 피하고 설명을 할 땐 누구나 명확히 이해할 수 있도록 주석을 달아야합니다.
   • 모호한 변수, 반환값들을 주석을 통해 설명합니다.
2. 복잡한 코드를 설명하는 주석
   • 가끔은 코드가 너무 복잡해서 코드를 만든 사람도 이해하기 어려운 경우가 있다. 이 때 해당 로직이 어떻게 동작하고, 어떤 값을 요구하며, 어떤 결과를 반환하는지 설명하는 주석이 있다면 협업자는 좀 더 빠르게 이해하고 코드를 활용하거나 개선할 수 있다.
3. TODO 주석
   • 할 일을 잊어버리지 않을 수 있다. 다만 작업을 끝내면 //TODO 주석을 지워야 한다. 주기적으로 점검을 통해 필요없어진 주석을 지우는 것이 좋다.
   • 완전하지 않아서 추가 작업이 필요하거나 앞으로 작업할 할 일이 있다면 //TODO 주석을 남기는 것이 좋다.
4. 결과를 경고하는 주석
   • 협업하는 사람에게 function의 결과를 경고할 목적으로 주석을 제공하는 것이 좋다.
5. 외부 코드를 사용했을 때 원본 소스에 정보를 제공하는 주석
   • 누가 코드를 제공했고, 여전히 잘 동작하는지, 어떻게 개선할 수 있는지에 대한 내용을 확인할 수 있다. url을 넣어두면 차후에 참조를 찾을 때 빠르게 찾을 수 있다.
   • 때때로 구글링을 통해 찾은 코드를 가져와서 활용하는 경우가 있다. 이때 원본 소스에 대한 정보를 주석으로 달아두면 미래의 작업자에게 도움이 될 수 있다.

 

나쁜 주석

1. 주절거리는 주석
   • 특별한 이유 없이 작성한 주석은 지우는 것이 좋다.
2. 같은 이야기를 중복하는 주석
   • 코드에서 파악할 수 있는 부분을 그대로 주석으로 적어두는 것은 필요없는 행동이다.
3. 이력을 기록하는 주석
   • 주석을 통해 이력을 기록하기 보다 소스 코드 관리 시스템을 활용하자.
4. 위치를 표시하는 주석
   • 소스 파일에서 특정 위치를 표시하려는 주석(예를 들어 //action을 시작하는 시작점이다를 표현하는 경우)이 있다. 이는 가독성을 낮추는 행동이며 반드시 필요할 때만 사용하는 것이 좋다.
5. HTML 주석
   • HTML 코드를 작성할 때 사용할 수 있는 주석은 코드가 길어지고 어수선해질 수 있다. 또한 주석을 업데이트하는 등 관리가 어렵기 때문에 피하는 것이 좋다.

---

 

이렇게 좋은 주석을 다는 방법에 대해 알려드렸습니다. 무조건 이렇게 해야한다는 의미는 아니지만 평소 주석을 달 때 어떤 내용을 담아야할지 생각해보는 시간이 필요한 것 같아요!

그럼 다음 글에서 만나요!!