개발이라는 건 기록의 작업이다. 코드 한줄을 작성하더라도 이유없는 코드가 없다. 이런 이유로 코드를 작성할 때 그 근거를 기록으로 남길려고 하고 권장한다.

당신은 어떤 방식으로 기록하고 있나? Jira와 같은 티켓 관리 시스템을 이용할 수도 있겠고, 혹은 Confluence에 일지를 쓸수도 있겠다. 하지만 당신이 개발자라면 이 문제를 개발자스럽게 풀고 있을 것이라고 생각한다.

코멘트?

가장 흔하게 생각할 수 있는 방법이고 실제로 많은 개발자들이 작업에 대한 이력을 코멘트로 남긴다. 그림에서 보이는 녹색 코멘트가 가장 대표적인 경우다. 코드를 작성한 이유가 무엇이며 동작이 이런 방식으로 움직인다고 설명한다.

하지만 이런 코멘트는 비추다. 첫번째 이유는 이 코멘트에 사람들이 집중하지 않는다. 개발자라면 코드를 읽을려고 하지 문제가 있지 않는한 코멘트를 읽지 않는다. (사실 정말 그런지도 의문이다. 문제가 있다면 디버깅을 하거나 해당 코드 영역에 대한 테스트 코드를 살펴보지 않을까?)

정말 심각한 문제는 코드를 작성한 본인(들)도 본인들의 코멘트를 지키지 않는다는 사실이다. 기록을 해두면 된다라고 생각하지만 수정 가능한 코드에 대한 기록은 관리가 필요하다.  즉 코드가 바뀌면 코멘트도 바뀌어야 하는데 거의 대부분 코드만 수정하지 코멘트는 수정하지 않는다. 여러 이유가 있지만 그만큼 코멘트는 최초 작성자를 포함해 제대로 읽히지 않는다는 것을 의미한다.

코멘트는 남기지 않는게 좋다. 당신이 남기는 코멘트는 100% 쓰레기가 된다. 이런 쓰레기를 남기는 활동은 정신 건강에 좋지 않다. 그럼에도 불구하고 굳이 코멘트를 남기겠다면 코드 중간에 남기지 말고 Docs 문서 생성이 가능한 메소드 상단에 붙혀준다.

코드 중간에 남기는 코멘트는 진심 백퍼 쓰레기다. 되려 상단에 남기는 코멘트는 메소드의 의미를 설명해주기 때문에 사람들의 눈에 보여질 가능성도 훨 높을 뿐만 아니라 수정 가능성도 덩달아 높아진다.

의미에 이름을 주자.

특정 코드 블럭이 의미나 목적을 가진 부분이라면 이걸 굳이 코멘트로 남길려고 하지 말자.

질척거리는 코멘트보다 함수 혹은 메소드로 의미에 이름을 부여하는 것이 백배 좋다. 메소드의 이름을 적어주고 따로 Javadoc를 목적으로 한 것인지는 모르겠지만 따로 코멘트를 남기는 경우가 있다. 그렇게 남기는 설명이 메소드의 의미를 부연하기 위한 것이라면 차라리 이름을 충분히 길게 작성하자. 코드를 읽는 사람이 두 번 읽게 하는 것보다는 한번 읽어서 의미를 파악할 수 있게 하는게 좋다.

개발자가 싫어해야할 것은 같은 어떤 의미에서든 중복을 없애는 것이다. 그리고 이 규칙은 메소드 이름과 코멘트의 경우에도 마찬가지다. 그리고 이제 메소드의 코드를 최대한 간결하게 작성해서 술술 읽히게 만든다. 충실한 코멘트보다는 쉽게 읽히는 코드가 다른 개발자 혹은 동료를 위한 배려다.

소스 관리 도구들을 활용하자.

그럼에도 불구하고 다른 기록을 남기고 싶은 욕구가 생기는 경우가 있다. 개인 경험상 특정 버그 혹은 요청 티켓을 처리한 경우가 대표적이다. 지금 변경한 코드가 이 티켓에 해당하는 변경이라는 것으로 남기고 다른 사람도 그 티켓을 참조했으면 하고 바라기 때문이다. 앞서 이야기했지만 그렇다고 이걸 코멘트로 코드안에 남겨봐야 의미없다. 더 좋은 방법이 없을까?

코멘트보다 좀 더 효과적인 방법으로 추천할만한 내용은 커밋 로그(Commit log)를 활용하는 것이다.  커밋은 코드의 “특정 작업 단위가 마무리됐다는 것“을 말한다. 마무리된  작업의 내용을 설명하는 것이 커밋 로그이다. 또한 온라인 코드 리뷰 자체도 이 커밋 단위로 리뷰가 진행된다. 따라서 작업 설명은 충실하면 충실할수록 좋다. 작업 내용의 충분한 이해를 바탕으로, 리뷰어가 코드를 살펴보고 리뷰를 남겨준다면 리뷰를 받는 사람에게 더 도움이 된다.

결론은 충실하면 좋다긴 하지만 Source repository로 뭘 사용할 것인가에 따라 접근 방법이 틀려진다. 국내에서는 아직 SVN을 Repository로 사용하는 회사 혹은 개발팀이 많다. 하지만 알다시피 SVN은 중앙에서 소스를 관리한다. 그게 뭔 문제??? 관리 대상이 작다면 별 문제가 안되지만, 누구나 알듯이 많아지면 주구장창 느려지는 문제점이 있다. 더구나 SVN은 커밋을 하게되면 이를 서버에 전송하여 저장한다. 각 커밋 단위가 가지는 의미가 상당하다.

이런 이유로 SVN을 사용하는 대부분의 팀에서는 한 커밋 단위에서 자잘한 코드 변경을 커버하기 보다는 의미있는 단위로 작업하라고 권고한다. 한 커밋 변경에서 변경되는 작업 분량이 커지게 된다. 이 내용을 상세하기 적을려면 분량이 상당해진다. 바꿔 말하면 변경 내용을 알아보게 로그 형태로 적기 힘들다. 잘 적을까? 당연히 안적게 된다. 남길 수 있다면 티켓 번호 정도? 따라서 변경의 주요 내용을 커밋 로그에서 따라잡기 어렵다. 이 상황이 지속된다면 차라리 변경 주요 내용을 코멘트로 님기는게 더 나은 방법일 수도 있다.

그러니까 git을 사용해야 한다. Distributed source repository가 주는 장점이랄까? 혹은 로컬에서 자신의 Copy를 가지고 움직이기 때문에 갖는 장점일지는 모르겠다. 가볍고 빠른다. 그리고 Remote repository에 push를 통해 업로드하기 때문에 각 Commit 단위가 갖는 무게가 상대적으로 가볍다.

Git을 Source repository 사용한다면 다음의 규칙을 사용해서 로깅을 남겨보자.

» 서로 독립적인 변경이 있다면 각각에 대해 모두 커밋 로그를 남긴다. 예를 들어 불필요한 코멘트를 삭제했다면 그것도 커밋의 단위이고, 오타 한글자를 수정했었도 것도 따로 커밋한다.

» 코드 작성/변경 자체가 좁은 범위에 대해 이뤄진다. 로그에 쓸말도 많지 않아야 한다. 50 ~ 80자 이내로 코멘트를 작성하자. 바꿔 이야기하면 이 정도의 내용으로 커버될 내용이 한번의 커밋 대상이어야 한다.

» 다른 사람들과 공유해야하는 경우에만 Remote branch에 push한다. 모 회사의 광고 아닌 광고에 보면 불이 나도 push는 하고 가라는 말이 있긴 하지만 branch 방식으로 PR을 관리한다면 간간히 push를 하지 말고 자주 push를 하는게 좋다. 그렇게 모인걸 PR 날리면 땡이니 Remote에 얼마나 자주 push를 하던 문제가 안된다. (불날때 먼저 나가는게 중요하지 push는 하고 가라는 우스개 소리 아닌 소리를 하는 회사는 별로다.)

» 최종 PR의 타이틀은 간결해야한다. 내용에는 PR통해 반영될 기능들에 대한 설명과 리뷰를 해줬음 하는 대상자들의 이름을 적어둔다. 그리고 사람들 사이에 대화가 이어지면 된다.

 

Source repository를 쓴다면 이런 목적이어야 하지 않을까? 변경이 왜 일어났고, 언제 일어났으며, 누구에 의해 발생했는지를 한 눈에 명확하게 파악할 수 있다. 와중에 git 같은 툴을 사용하고 있다면, 코드가 발전되어 가는 형상을 관찰할 수도 있다. 그렇기 때문에 git을 써야한다.

개인적으로는 코드에 코멘트를 하나도 남기지 않는 것이 최선이라고 생각한다. 코드에 남기는 코멘트는 파일이 최초로 만들어졌을 때 자동 생성되는 작성자 이름과 작성일 정도면 충분할 것 같다. 그 이외에 자동으로 생성되는 나머지 코멘트들은 모두 지워버린다. 남겨두면 그게 득이 되는 경우를 본적이 없는 것 같다.

코딩 세상에서 미니멀리즘을 추구해야할 부분이 바로 이 포인트이지 않을까 싶다.