답변:
내가 묻는 것이 무엇인지, 다른 사람들이 사용할 수 있도록 코드가 충분히 문서화되고 작성되도록하는 가장 좋은 방법은 무엇입니까?
오픈 소스로서 가장 중요한 의견은 저작권 및 라이센스 계약 의견입니다. 모든 파일의 시작 부분에 큰 주석을 달기보다는 저작권을 간단히 지정하고 루트 디렉토리의 license.txt를 읽는 짧고 달콤한 주석을 사용할 수 있습니다.
나는 당신이 항상 모든 것을 언급해야한다는 것을 알고 있으며 모든 방법에 대해 @params 기능을 넣을 것이지만 일반적인 다른 팁이 있습니까?
모든 것을 주석으로 처리 하시겠습니까? 아닙니다. 실제로 주석이 필요한 코드를 주석으로 처리하십시오. 드물게 의견을 말하십시오. 코드 청크의 잠재적 사용자로서, 다음 두 가지 버전의 클래스 정의 중 어떤 것을보고 싶습니까?
버전 A :
class Foo {
private:
SomeType some_name; //!< State machine state
public:
...
/**
* Get the some_name data member.
* @return Value of the some_name data member.
*/
SomeType get_some_name () const { return some_name; }
...
};
버전 B :
/**
* A big long comment that describes the class. This class header comment is very
* important, but also is the most overlooked. The class is not self-documenting.
* Why is that class here? Your comments inside the class will say what individual parts
* do, but not what the class as a whole does. For a class, the whole is, or should be,
* greater than the parts. Do not forget to write this very important comment.
*/
class Foo {
private:
/**
* A big long comment that describes the variable. Just because the variable is
* private doesn't mean you don't have to describe it. You might have getters and
* setters for the variable, for example.
*/
SomeType some_name;
public:
...
// Getters and setters
...
// Getter for some_name. Note that there is no setter.
SomeType get_some_name () const { return some_name; }
...
};
버전 A에서는 클래스 자체를 제외한 모든 것을 문서화했습니다. 일반적으로 수업은 자체 문서화가 아닙니다. 버전 A에있는 주석은 전혀 쓸모가 없으며, 쓸모없는 것보다 더 나쁩니다. 이것이 "모든 의견"태도의 핵심 문제입니다. 개인 데이터 멤버에 대한이 간결한 설명은 아무 것도 전달하지 않으며 게터에 대한 doxygen 설명은 음의 값을 갖습니다. 게터 get_some_name()는 실제로 주석이 필요하지 않습니다. 그것이 무엇을하고 그것이 무엇을 리턴하는지는 코드에서 명백히 명백합니다. 세터가 없다는 것-그것이 없기 때문에 추론해야합니다.
버전 B에서는 주석이 필요한 것을 문서화했습니다. getter에는 doxygen 주석이 없지만 setter가 없다는 주석이 있습니다.
의견 수를 세고, 코드에 대한 변경 사항을 반영하기 위해 의견이 자주 유지되지 않도록주의하십시오.