본문 바로가기
[Kotlin Tutorial] Documenting Kotlin code [Kotlin Tutorial] Documenting Kotlin code 출처 : Kotlin in action 1. Writing Kotlin documentation comments -Java 의 Javadoc 만들 때와 비슷하다.Kotlin 의 것은 KDoc 이라 부른다. -KDoc 은 /** 로 시작하고 tag 는 마찬가지로 @ 로 시작한다.Javadoc 과의 가장 큰 차이가 있다면 HTML 대신 Markdown 을 사용한다는 것이다./** * Calculates the sum of two numbers, [a] and [b] */fun sum(a: Int, b: Int) = a+b 정의를 참조하려면 [ ] 안에 이름을 넣어주면 된다. cf) Markdown 은 text-to-HTML conve.. 2017. 9. 20.
[Effective Java] 스레드 안전을 문서화 하자. [Effective Java] 스레드 안전을 문서화 하자. - 클래스 행동을 문서화하지 않으면, 프로그래머는 가정에 의존해서 그 클래스를 사용해야 한다. 만일 그런 가정들이 잘못되면, 그로 인한 프로그램은 불충분한 동기화나 과도한 동기화를 하게 될 것이다. 어떤 경우든, 심각한 에러가 유발될 수 있다. - 메소드 선언부의 synchronized 변경자는 메소드의 상세 구현 부분이지 외부로 제공되는 API 가 아니다. 즉 Javadoc 에 synchronized 가 공개되지 않는다. synchronized 변경자가 있다는 것이 스레드 안전을 문서화하기에 충분한 것은 아니다. 동시적 사용을 안전하게 하려면, 해당 클래스가 어떤 수준의 스레드 안전을 지원하는지 명확하게 문서화해야 한다. - 다음은 스레드 안전.. 2017. 3. 14.
[Effective Java] 메소드가 던지는 모든 예외를 문서화하자. [Effective Java] 메소드가 던지는 모든 예외를 문서화하자. - Javadoc 의 @throws 태그를 사용해서 항상 checked 예외는 별도로 선언하고, 각 예외가 발생하는 상황을 정확하게 문서화하자. 메소드가 던지는 예외가 많다고 해서 메소드 명세에 각 예외를 정확하게 선언하지 않고, 그 예외 클래스의 대표적인 슈퍼 클래스만 함축해서 나타내면 안 된다. - unchecked 예외의 문서 내역은 메소드가 성공적으로 실행되기 위한 사전조건(precondition)을 효과적으로 나타낸다. - 인터페이스에 정의된 메소드의 경우 자신이 던질 수 있는 unchecked 예외를 문서화하는 것이 "특히" 중요하다. 그 인터페이스의 보편적 계약 중 일부분이 되며, 인터페이스를 구현하는 여러 구현체들 간의.. 2017. 2. 28.
[Effective Java] 외부에 제공하는 모든 API 요소에 대해 문서화 주석을 넣자. [Effective Java] 외부에 제공하는 모든 API 요소에 대해 문서화 주석을 넣자. - 사용 가능한 API 라면 반드시 문서화해야 한다. 만일 문서화 주석 규칙에 친숙하지 않다면 배워야 한다. - API 를 문서화하려면, 외부에 제공하는 모든 클래스, 인터페이스, 생성자, 메소드, 필드의 선언부 앞에 문서화 주석을 넣어야 한다. 만일 어떤 클래스가 직렬화될 수 있다면 직렬화 형태도 문서화해야 한다. - 문서화 주석이 빠진 API 를 사용하는 것은 실망스럽고 에러가 생길 가능성이 많다. 유지보수 하기 쉬운 코드를 작성하려면 외부에 공개되지 않는 대부분의 클래스, 인터페이스, 생성자, 메소드, 필드에 대해서도 문서화 주석을 작성해야 한다. - 메소드의 문서화 주석에서는 메소드와 클라이언트 사이의 계.. 2017. 1. 23.
[Effective Java] 매개 변수가 유효한지 검사하기. [Effective Java] 매개 변수가 유효한지 검사하기. - 대부분의 메소드와 생성자는 자신들의 매개 변수로 전달될 수 있는 값에 제한을 둔다. 그런 모든 제약은 명확하게 문서화해야 하며, 메소드 몸체 코드의 맨 앞에서 검사하도록 해야 한다. 이것은 에러가 발생한 후 가능한 빨리 검출해야 한다는 일반적 원칙의 특별한 경우이다. 만일 사전 검사에 실패하면 에러의 검출이 불확실하게 되고, 에러가 생긴 소스 코드를 찾기가 더욱 어려워진다. - public 메소드의 경우는 javadoc 의 @throws 태그를 사용해서 매개 변수 값의 제약을 위반했을 때 발생되는 예외를 문서화한다. 일반적으로 IllegalArgumentException, IndexOutOfBoundsException, NullPointe.. 2017. 1. 9.
[Effective Java] private 생성자를 사용해서 인스턴스 생성을 못하게 하자. private 생성자를 사용해서 인스턴스 생성을 못하게 하자. - static 메소드와 static 필드만을 모아 놓은 클래스를 만들 경우 private 생성자를 사용해서 인스턴스 생성을 못하게 하자. - 명시적으로 지정한 생성자가 없을 때는 컴파일러가 디폴트 생성자 ( default constructor ) 를 생성한다. 이는 javadoc 프로그램으로 생성하는 API 문서에도 나타나므로 인스턴스 생성이 가능한 클래스로 오인될 수 있다. public class UnilityClass{ private UtilityClass(){ throw new AssertError(); } ... } - 이 방법은 sub class 를 가질 수 없다는 단점이 있지만, Utility 함수들은 대부분 상속을 위해 설계되지.. 2015. 4. 5.
Eclipse 에서 Support v4 Javadoc 연결하기 Eclipse 에서 Support v4 Javadoc 연결하기 android-support-v4.jar 가 위치한 libs 폴더에 아래 파일을 생성하고,그 안에 src 와 doc 에 대한 정보를 기입해준다. 파일명 : android-support-v4.jar.properties doc=[android SDK folder]\\docs\\referencesrc=[android SDK folder]\\extras\\android\\support\\v4\\src 저 경로는 OS 종류에 따라 조금씩 다르겠죠?포인트는 빨간색으로 표시된 부분!! android SDK folder 를 잘 연결해서 support api 부분에서도 javadoc 을 봐서 더 편리하게 개발하시길~ Android, android-suppor.. 2015. 1. 6.
반응형