爲什麼我需要在C＃/ .Net代碼中使用這些討厭的註釋？

我建立的應用程序和要求，一個是使用註釋像這樣的：爲什麼我需要在C＃/ .Net代碼中使用這些討厭的註釋？

/// <summary> 
/// Creates new client. 
/// </summary> 
/// <param name="uri">The URI.</param> 
/// <param name="param">The param.</param> 
/// <returns></returns>

我所知，這很容易爲各種樣的工具來生成基於這些個XML的文檔。但它顯着降低了代碼可讀性，這正是我們人類試圖實現的目標。

這種方法是否可以被.Net中的其他技術所取代？有什麼更好的方法來提高代碼的可讀性和清潔度？

來源

2013-08-20 Roman Pushkin

「改善代碼可讀性和清潔度的更好方法是什麼」編寫自定義代碼而不使用許多註釋代碼 – wudzik

它以何種方式降低代碼可讀性？它存在於方法本身之外。 –

此外，這可以在VisualStudio中摺疊 –

當有人在通過您的方法使用智能感知時，應該在Visual Studio上彈出該信息。這將節省時間，因爲誰使用你的代碼不需要進入你的代碼（這意味着你也不需要暴露你的任何代碼）並查看你寫過的其他評論。

我認爲，文檔在保持簡短和重點的情況下永遠不會是一件壞事，它不會影響代碼的可讀性。

來源

2013-08-20 07:06:29 npinti

是的，我明白這一點。但同時，很多工具會自動爲你粘貼所有這些XML註釋（GhostDoc）。在一些公司，他們甚至懶得寫更多。他們有這些自動生成的評論是可以的。無論如何，我期待的答案就像是使用工具來隱藏xml註釋，或者以更好的方式來組織它們。 –

@RomanPushkin：你可以看看這個鏈接：http://stackoverflow.com/questions/8696586/c-sharp-hide-and-unhide-comments也許有一些你可能會遇到的信息。 – npinti

XML註釋並不是爲.NET項目生成文檔的唯一方式，而且它們很難看。它們適用於Intellisense或API幫助文件生成，但不包括代碼本身的文檔，只是暴露的API。像nocco這樣的工具解決後一種場景 –

雖然使用第三方DLL確實intellisense會傷害你嗎？

我不這麼認爲。這是使用此評論的主要原因之一。

假設你正在糾正一個dll（或者編寫一個別人會使用的類），對他/她來說，當他類型化時，他知道該方法做了什麼以及參數是如何工作的對他/她沒有幫助嗎？

來源

2013-08-20 07:07:45 Ehsan

VS文檔和註釋不會降低大多數人的代碼可讀性，反過來也是如此。如果您覺得這些註釋使得代碼不易讀取，您可以摺疊它們，甚至改變它們繪製的顏色。

但是想想當你把光標放在一個函數上面並且方法的信息和它的參數出現時它是多麼有用。這是最好的可讀性

來源

2013-08-20 07:09:34

，這正是人們在cshtml之前對aspx的想法 –

你絕對不應該避免這些評論！他們爲Visual Studio提供IntelliSense，並且可以形成自動文檔工具（如SandCastle）的基礎。據我所知你的唯一選擇就是用這個技巧（獲得所有這些功能）。

爲了提高可讀性，您可以使用Visual Studio中第一個標記旁邊的[ - ]將每個註釋最小化。這樣你只會看到第一行。這對於日常工作中的代碼很有幫助。

我還發現導航下拉列表有助於在類中定位方法，如果發現xml使其更難以瀏覽/瀏覽。

但使用起來是一件好事，你習慣了身邊有他們

來源

2013-08-20 07:11:57 havardhu

不同的文件格式都適用於不同的場合。

XML註釋最適合自動幫助文件生成和智能感知。根據需要，它們比其他方法更詳細，因爲它們需要特定的標籤才能生成文檔。雖然語法可能會更好，但是記住，當所有人都認爲XML是一個很酷的想法時，它們就會被創造出來。

對於一般評論，您可以使用識字編程風格和工具如nocco來創建和顯示HTML頁面。該工具提取註釋並將其顯示在代碼旁邊的HTML頁面中。 nocco頁面本身就是nocco的輸出nocco.cs

Nocco甚至使用Markdown進行格式化。

當然，你可以混合和匹配方法，例如。對公共方法使用XML註釋，對內部評論使用文字註釋。

來源

2013-08-20 07:16:05

爲什麼我需要在C＃/ .Net代碼中使用這些討厭的註釋？

回答

相關問題