ฉันเดาว่าสิ่งที่ฉันถามคืออะไรจะเป็นวิธีที่ดีที่สุดในการตรวจสอบให้แน่ใจว่ารหัสของฉันได้รับการบันทึกไว้อย่างเพียงพอและเหมาะสมสำหรับผู้ใช้
ในฐานะที่เป็นโอเพ่นซอร์สความคิดเห็นที่สำคัญที่สุดของทั้งหมดคือความคิดเห็นลิขสิทธิ์และข้อตกลงใบอนุญาต แทนที่จะแสดงความคิดเห็นที่ยาวมากในตอนเริ่มต้นของไฟล์ทุกไฟล์คุณอาจต้องการใช้คำย่อสั้น ๆ ที่หวานชื่นซึ่งระบุลิขสิทธิ์สั้น ๆ และอ้างอิงผู้อ่านไปที่ 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 ฉันได้ทำเอกสารสิ่งที่ต้องการแสดงความคิดเห็น ผู้ทะเยอทะยานไม่ได้มีความคิดเห็น doxygen แต่มันมีความคิดเห็นที่กล่าวถึงว่าไม่มี setter
ทำให้ความคิดเห็นของคุณนับและระวังว่าความคิดเห็นที่เกิดขึ้นบ่อยครั้งจะไม่ได้รับการปรับปรุงเพื่อให้สอดคล้องกับการเปลี่ยนแปลงของรหัส