Documents

Javadoc @author 태그 사용을 멈춰라

이 글은 원작자의 동의를 얻고 번역한 글입니다. 번역에 서툴러 매끄럽지 못하거나 어색한 부분이 있을 수 있으며 이러한 부분에 대해 피드백 주시면 감사하겠습니다. 원문 링크는 다음과 같습니다.

Javadoc 태그인 @author 를 아직도 사용하고 있는가? 아마도 다시 생각할 시간이다. 현시점에서 왜 사용하지 말아야하고 유해한지 이유에 대해 살펴보자.

Javadoc @author tag

Javdoc에 있는 @author 태그는 파일의 원작자와 중요한 변경을 가한 모든 기여자를 나타낸다.

/**
* Validator used to check whether given string is
* no longer than the specified amount of characters.
*
* @author Vojtech Ruzicka
*/
public class MaxLengthValidator {
  ...
}

자세한 내용은 How to Write Doc Comments for the Javadoc ToolJavaDoc reference guide에서 확인할 수 있다.

What is wrong with @author

기본적으로 Javadoc을 생성하는데 있어서 디폴트 옵션이 아니기 때문에 @author 태그의 내용은 포함되지 않는다. 문서에 author 정보를 포함하기 위해서는 -author 파라미터를 명시적으로 지정해야 한다. 그러므로 author 정보는 소스 코드를 보고 있는 사람에게만 보여진다. 이 때, 버전 관리 시스템(Git 혹은 SVN)에는 훨씬 더 나은 원작자와 기여자에 대한 정보 소스가 있고, 주석에 이러한 정보를 추가하는 것은 중복이며 불필요한 노이즈가 된다. 나아가 파일의 각 한줄마다 누가 언제 편집했는지도 확인할 수 있다.

Authors and time of changes as shown in IntelliJ Idea 2016.1

또한 @author 태그와 달리 VCS를 활용하는 것은 항상 정확하고 최신 정보를 확인하게 된다. 주석은 금방 쓸모 없거나 구식의 정보를 가지게 되는 경향이 있다. 개발자는 코드 변경시 주석도 함께 업데이트하는 것을 잊거나 무시할 때가 많으며, 리팩토링 후에는 원작자가 개발했을 때와 전혀 다른 코드가 되기 마련이다. 또한 주석에 언급된 원작자나 기여자가 회사에 없거나 프로젝트를 떠났을 수도 있다는 것은 말할 것도 없다.

IDE templates

더욱 심각한 것은 원작자와 생성 일자를 나타내는 기본 non-Javadoc 템플릿이며, 일부 IDE는 자동으로 파일을 생성할 때마다 추가된다. 다음은 IntelliJ Idea(as of 2016.1)에서 사용하는 기본 설정이다.

/**
 * Created by vojtech on 5/7/2016.
 */
public class BrandNewClass {
}

이것은 @author Javadoc의 단점을 모두 포함하고 있다. Javadoc과 달리, IDE를 통해 Javadoc 팝업을 호출해도 보여지지 않을 뿐더러 자동 완성도 활용할 수 없다. 그러므로 author가 포함되기를 원한다면 해당 템플릿이 아닌 @author 태그를 사용해야한다.

역주

기본적으로 IDE에서 추가해주는 템플릿은 원작자가 아닌 파일 생성자creator이다. 설계자가 인터페이스만 설계해놓는다면 이미 썩은 주석이 되어버린다. 또한, PC에 사용자명을 변경하지 않거나 회사에서 지급받은 PC라면 더욱이 쓰레기 정보를 담게 된다.

/**
 * Created by user on 10/6/2019
 */
public class BrandNewClass {
}

Still want to keep it?

아직도 확신하지 않는가? @author 태그를 포함해야하는 회사 정책이 있거나 (다른 이유가 있어서) 사용을 원하는 경우가 있을 수도 있다. 이 경우 현재 지정된 파일의 담당자를 표시하는 것을 제안한다. 이는 특히 많은 개발자들과 함께하는 대규모의 장기 프로젝트에서 유용하다. 거대하고 오래된 코드베이스로 작업하는 동안에는 누가 기여자인지 아는 것보단 특정 파일 또는 모듈과 관련해서 누구와 연락해야 하는지를 아는 것이 훨씬 더 중요하다. 그러니 태그를 최신 상태로 유지해라. 그러나 최신 상태로 유지해야 할 파일이 많다면 개별 파일이 아닌 전체 모듈의 author information on package level을 포함하는 것이 나을 수 있다.

Conclusion

ApacheGradle도 마찬가지로 @author 태그 사용을 중지하는 것을 제안한다. 계속 사용할 경우 최소한 정보를 최신 상태로 유지해야 한다.

번역 후기 및 사견

여기까지 번역 내용이다. 요즘 @author@since 에 대해서 많은 생각이 있었다. 당연하다고 생각했던 부분들도 사람마다 다르게 생각하고 근본적으로는 같은 생각이면서도 다른 결과가 나오더라. 생각을 뒷받침 할, 혹은 생각의 전환이 될 만한 글을 찾다가 이 글을 보게 되었다. 내 생각과 비슷해서 원작자에게 메일을 통해 허락받아 번역해보았다. 이 또한 좋은 경험인 것 같다.

이제는 모든 스펙을 정의하고 한번 개발되면 변경될 일이 적은 시대는 지나갔다고 본다. 요구사항은 계속 변화하고 추가되며, 한 사람이 특정 스펙 개발을 도맡아 하지 않고 팀 내 여러 개발자가 협업하고 개선해나간다. 이처럼 author와 contributor 정보는 빠르게 변경되고 그만큼 누락되는 일도 많아진 것이다.

코드를 볼 때 스펙에 관해서 말고는 author를 통해 원작자에게 물어볼 일이 없어야 한다고 생각한다. (즉, 소지자의 의미보단 스펙에 대해서 많이 알고 있는 사람이 되어야 하지않을까? 위 글에 담당자를 표시하는 것과 같은 맥락이다.) 그만큼 읽기 쉬운 코드를 작성해야하며, 또한 어려운 코드에 부딪혔을 땐 점차적으로 개선해나가야한다. author가 내가 아니라고 그냥 넘어가서도 안된다(모든 코드에 대해서 오너쉽을 가지자).

@author 는 코드에 대한 오너쉽을 가지기 위한 정보가 아니다. 내 코드라고 명시할 이유가 없다. 우리 팀 내 모든 코드에 대해서 오너쉽을 가져야 한다. 이는 반대로 '내 코드가 아니야' 혹은 '옛날 코드여서 그래' 라는 합리화를 할 수 있을거라 생각한다. 항상 보이스카웃 규칙으로 왔을 때 보다 더 깨끗하게 만들고 떠나야한다.

Always leave the campground cleaner than you found it.

— The Boy Scout Rule

나중에 한번에 수정하자는 생각은 버려야 한다. 조금씩 변화해야 한다. 나중은 결코 오지 않는다.

Later equals never

— Leblanc's Law

잦은 변경에 충돌conflict이 두려울 수 있다. 하지만 언제든 충돌이 일어날 것이라고 생각하자. 이미 많은 IDE와 tool에서 diff와 충돌 해결에 대한 기능을 제공한다. (이런 툴이 제공되고 지속적으로 개발/개선되고 있다는 것은 충돌은 항상 일어나고 해결해나가야 한다는 의미가 아닐까.)

개발자는 자신이 짠 코드에 대해서 더 오너쉽을 갖고 남이 수정하는 것을 두려워하는 경향이 있다. 그만큼 시간을 투자해서 만든 코드이기 때문에 어느정도는 이해한다. 하지만 개발자가 1명이 아닌 이상 그런 생각은 버려야 한다. (나 또한 많이 고생하거나 개인적으로 맘에 드는 코드를 작성하면 VCS에 다 나와있음에도 내 이름을 적을 때가 있다..) 함께 더 나은 코드를 만들어가야 하고, 잘 만들어진 TCTest Case가 있다면 변경에 두렵지 않을 것이다. TC에도 왠만하면 javadoc author는 필요 없다고 생각한다. 스펙에 대해서 담당자가 있다면 추가할 수 있겠지만 TDD를 한다면 TC 또한 계속 변화할 것이며 팀원 모두의 책임이 있어야 한다. (당연히 TC도 이해하기 쉽게 짜야한다..)

이제 Javadoc 태그는 문서를 만드는 것보다 규약을 통해서 개발의 편의성을 높이기 위함인 것 같다. 물론, Javadoc을 활용해서 문서를 만드는 조직에 해당하는 얘기는 아니다.

마지막으로, 도움을 주지 않는 주석이 그만큼 관리가 안되는 법이다. 불필요한 주석보단 도움이 되는 주석을 달아놓자. (그리고 가능하면 주석이 필요 없이도 이해할 수 있는 코드를 작성하자)

java