技術備註 0

如何撰寫 Lua 技術備註

沒有撰寫 Lua 技術備註的官方指南。您可以閱讀作者指南和技術備註元素，這些文件來自 Macintosh 技術備註，但閱讀這些文件只是為了了解技術備註的樣貌；Lua 技術備註的格式較為非正式。

以下是撰寫 LTN 的個人（且自我參照！）觀點。

如何撰寫 LTN

作者 Reuben Thomas

摘要

LTN 應具有下列結構

摘要
問題 - 動機和陳述
解決方案 - 說明
說明和理由
缺點和建議的改進
結論

問題

Lua 是一個極具經濟效益的工具，可解決許多程式設計問題。不幸的是，它的經濟性和設計靈活性可能會讓新手感到困惑：他們可能會找到一個笨拙的解決方案來解決自己的問題，或者更糟的是，根本看不到解決方案，而其實有一個簡單且優雅的解決方案等待著被發現。與大多數語言的使用者不同，這些使用者只是用這些語言進行程式設計，Lua 程式設計師通常會想要嵌入、介面，甚至變更 Lua。

各種函式庫和工具已逐漸發展以滿足許多這些需求，例如 tolua、CGILua 和 LuaSocket。然而，有些需求較為抽象，無法輕易透過工具或函式庫來滿足；例如以下問題：如何將 Lua 整合到我的 C++ 程式中？如何將 Lua 介面到另一種語言？如何避免暫停遊戲以進行垃圾回收？像這樣的問題最適合透過類似 HOWTO 的文件來解決，而這就是 LTN 系列文章的目標。但 LTN 應如何撰寫才能最好地滿足這個需求？

LTN 應具備下列屬性

它應解決實際需求。根據經驗法則，如果您有動力撰寫 LTN，它很可能正在解決實際需求，儘管如果其他人要求解決它所解決的問題，那就更好了。
它應簡潔。這讓其他人能夠盡快閱讀、理解和使用其中包含的知識；或者，另一方面，如果對他們沒有好處，就將其丟棄。作為這項工作的一部分，不應有必要閱讀整個 LTN 才能知道它是否符合您的需求。
它應該是權威性的。不準確或考慮不周的 LTN 可能比沒有還糟。同樣地，如果你有寫 LTN 的感覺，你可能知道自己在說什麼。Lua 設計師擔任這個系列的編輯，這也有幫助。

解決方案

解決方案分為兩部分：形式和內容。內容由作者決定；建議的 LTN 形式如下

摘要: 總結 LTN。
問題: 激勵問題：為什麼它很重要。以明確的陳述作結。這將有助於你和讀者專注。在這一節的結尾，讀者應該知道 LTN 是否對他們有用。
解決方案: 描述解決方案，不要過度說明原因和緣由。在這一節的結尾，趕時間的讀者應該能夠實作解決方案。
說明: 說明並證明你為什麼以這種方式設計你的解決方案。希望這將說服懷疑者，並向謹慎者保證你的解決方案很好，而且你知道自己在做什麼。周邊事項和非關鍵的細微差別可以在這裡探討（但保持相關性！）。
弱點: 討論你的解決方案的弱點，說明為什麼它們對其成功並非至關重要，並建議未來的改進。這正是你真正說服懷疑者你了解你的東西的地方。
結論: 總結，並對問題和解決方案提出更廣泛的觀點。

說明

這種結構遵循良好的技術寫作的標準做法。簡單的五部分結構鼓勵簡潔，適合大多數可以想像的 LTN，作者和讀者很容易遵循，並且允許大多數讀者從 LTN 中獲得他們需要的一切，從頭開始閱讀，直到他們已經足夠。

弱點

一體不適用於所有。建議的結構對某些人來說太詳細，對另一些人來說不夠，對另一些人來說根本不相關。我沒有說過如何實際寫作（請參閱 Strunk 和 White 的 "文體要素"，以獲得關於此方面的清晰簡潔的指導）。儘管如此，如果大多數作者遵循這種結構，他們希望會發現 LTN 更容易寫，而讀者肯定會發現它們更容易閱讀，因為它們具有共同的結構。

結論

Lua 的出色之處在很大程度上在於提供普遍適用的機制，而不是針對特定問題的解決方案。儘管如此，在使用 Lua 時經常會出現許多問題。其中一些較具體的問題由各種可用的函式庫和工具解決；LTN 嘗試解決一些較抽象的問題。此 LTN 為 LTN 提出了一個結構，以使其更有可能有用。

最後，Lua 程式設計師和 LTN 作者都應時時銘記 Lua 的第一法則：「用 Lua 做」。Lua 幾乎總是提供了解決問題所需的工具；只是要看如何使用它們。你很少需要認真使用 Lua API，更少需要更改 Lua 本身。在三個基本美德中，Lua 將懶惰排在不耐煩之前，將不耐煩排在傲慢之前。但當然，傲慢正是撰寫 LTN 所需要的！

最後更新：2004 年 3 月 18 日星期四下午 2:03:37 巴西時間，由 lhf 更新。