Ben soruyorum ne olduğunu, benim kod yeterince belgelenmiş ve diğer insanların kullanmak için doğru ifade emin olmak için en iyi yolu ne olurdu?
Açık kaynak olarak, hepsinin en önemli yorumları telif hakkı ve lisans sözleşmesi yorumudur. Her dosyanın başlangıcındaki büyük ve uzun bir yorumdan ziyade, telif hakkını kısaca belirten ve okuyucuyu kök dizindeki license.txt dosyasına yönlendiren kısa ve tatlı bir yorum kullanmak isteyebilirsiniz.
Her zaman her şeyi yorumlamanız gerektiğini biliyorum ve her yöntem için @params özelliğini koyarak olacağım, ancak genel olarak başka ipuçları var mı?
Her şeyi yorumlansın mı? Hayır. Gerçekten yorumlanması gereken kodu yorumlayın. Az miktarda yorum yapın. Bir kod parçasının potansiyel kullanıcısı olarak, bir sınıf tanımının aşağıdaki iki sürümünden hangisini görmeyi tercih edersiniz?
Versiyon 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; }
...
};
Versiyon 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 sürümünde her şeyi belgeledim - sınıfın kendisi hariç. Genel olarak bir sınıf kendini belgelemek değildir. A sürümünde yer alan yorumlar kesinlikle yararsızdır, hatta yararsızdır. "Her şeyi yorumla" tavrında kilit problem budur. Özel veri üyesindeki bu küçük kısa yorum hiçbir şey iletmez ve alıcıdaki doxygen yorumlarının negatif değeri vardır. Alıcı get_some_name()gerçekten bir yoruma ihtiyaç duymaz. Yaptığı ve döndürdüğü koddan açıkça anlaşılır. Belirleyici olmadığını - bunu çıkarmalısın çünkü orada değil.
B sürümünde yorumlanması gerekenleri belgeledim. Alıcının doxygen yorumu yok, ancak ayarlayıcı olmadığını belirten bir yorumu var.
Yorumlarınızı dikkate alın ve zaman zaman yapılan yorumların koddaki değişiklikleri yansıtmayacağına dikkat edin.