代碼示例

Question

我有多個程序員貢獻的的javadoc實例和一些例子包括用

/* 
* 
*/ 

格式化當我把這些例子爲javadoc註釋的意見，在這個例子中的註釋接近關閉的Javadoc評論。

/** 
* 
* /* 
* * 
* */ <-- right here 
* 
*/ 

有沒有一種正確的方法來處理這個問題，而不告訴大家他們不能以這種格式寫評論？

Answer 1

javadoc註釋使用HTML，所以編碼/作爲一個實體：/

/** 
* 
* /* 
* * 
* *&#47; <-- right here 
* 
*/ 

叫大家不要把那種評論在他們的代碼示例可能會更容易。

Answer 2

在我看來，如果代碼不是自明性的，或者至少簡單得足以通過簡短的描述來理解，那麼代碼應該被重構。它需要更短，或者變量需要更易於理解，或者邏輯需要重新思考。

無論如何，我不相信有一種解決方法，如果你想包括一個例子，那麼在這個例子中沒有任何評論。如果你真的必須有意見，請使用//表示法。

Answer 3

爲什麼要將評論的源代碼放入註釋中？

這聽起來像你的設計有什麼問題，如果這樣的事情是必要的。

Answer 4

Javadoc評論允許HTML。請在您的評論中附上<code>或<pre>元素中的代碼。例如：

/** 
* Outputs "Hello World" to the console. 
* 
* <code>System.out.println("Hello World");</code> 
*/ 

Answer 5

「/ * * /」註釋不能嵌套。 「//」註釋可以是，但它們只有在它們開始的行結束時纔有效。

一般來說，將實際代碼包含在JavaDocs中並不是一件好事 - 一方面，它們應該更抽象（而不是「如何」）的抽象（「爲什麼」）。