你如何記錄你的Less？

Question

我使用JSDoc來記錄所有我寫的JS，但我很好奇人們如何記錄他們的少。我想我可以使用JSDoc，但它看起來不正確，因爲更少不是JS。如果有一種標準的方式可能允許不同的IDE提供工具支持，我還想避免使用JSDoc記錄我的內容。

有沒有人知道一個標準的記錄方式較少？

Answer 1

記錄源代碼涉及不同的問題，並且可能有不同的目標，比記錄CSS，無論是更少還是其他任何變體。

源代碼涉及合同的類和方法，例如參數和返回值的類型和含義。它也可能有複雜的邏輯需要解釋，或處理多個條件，或處理各種邊緣情況。它可能正在實現一個第三方將使用的API，它應該有自己的可以「讀取」的獨立文檔。像JSDoc這樣的系統在設計時考慮到了這一切。閱讀代碼的人可以很容易地理解各種例程的目的和簽名以及邏輯，和註釋可以被處理成API文檔。

以類似的方式，源代碼通常按邏輯組織成模塊和類的層次結構。在閱讀文檔時，通常要從子類的描述跳轉到其超類的描述，或直到模塊級。像JSDoc這樣的工具通過大多數情況下通過吐出一組相互關聯的HTML頁面也使得這一點變得簡單。

另一方面，考慮一個像Underscore這樣的庫，只有上面的一些部分適用。沒有模塊，類或類層次結構。相反，它是一包工具。因此，真的不需要很多類似JSDoc的機器。相反，我想要做的是能夠讀取代碼並輕鬆查看正在發生的事情，或者獲得關於提供的功能的敘述，可能有一些代碼示例。這就是爲什麼他們使用Docco，正如評論者所建議的那樣。這是完美的。正如評論者所提到的，它可以用於幾乎所有的編程語言，包括CSS。與JavaScript等「語言」相比，CSS（通常）比較平坦，並且沒有參數和返回值「合同」的概念，也沒有複雜的計算，儘管在像LESS這樣的系統中，插入和計算。使用CSS，你也有這樣的情況：在許多情況下，CSS的效果是可視化的，比如說按鈕以特定大小的文本以某種方式着色。我們在CSS中有兩個潛在的註釋消費者：實際上正在查看CSS代碼的程序員，以及想要了解定義的樣式以及檢查其工作方式的UI設計者或實現者。

就我個人而言，我會在這裏採用兩種方法，映射到兩種類型的消費者。在CSS代碼本身，我只是簡單地評論一下，描述規則的目的和結構。與此同時，我會建立一個單獨的「styleguide」網站，其中包含所有樣式的可視化示例。已經有各種嘗試來自動創建這樣的風格指南，並取得了不同程度的成功。我沒有用過它們，所以不能說它們可能有多有用。就我個人而言，我會用手卷的風格指南去。

還值得指出的是，唯一比沒有文檔更糟糕的是文檔錯誤。無論您採用何種文檔方法，您都必須確保它的可持續性和可維護性。從這個意義上來說，簡單就好。

最後，讓我指出，大量文檔的需求與一組樣式和類的設計成反比。在巴洛克式的設計中，沒有太多意義，因爲分類不當，怪異的依賴和糟糕的命名，以及大量的文檔。相反，您可能需要關注重構您的CSS，因此它至少有更多的自我記錄。