我很确定，作为开发人员，我们都喜欢技术文档。我们喜欢阅读文档、编写文档，更不用说维护文档了，我喜欢它！我还知道每次创建类或方法时，都会考虑为其编写文档。我也很确定您喜欢编写文档，就像您偶尔喜欢吃美味的汉堡包一样。但有时，只是有时，您想放松一下，这次也许可以跳过文档部分。不幸的是，这种行为很快就会失控。所以在这篇文章中，我想谈谈开发人员生活中这个至关重要但经常被忽视和遗忘的部分。希望您会喜欢文档，了解您的代码为何有效，并帮助您、您的团队以及无数使用您的软件的人。为什么文档很重要通常，开发人员不会忘记他们两周前编写的代码。他们会在两个月后甚至更长时间后记住它。即使我们承诺我们永远不会忘记我们编写的任何代码，还有另一个更重要的原因是编写文档。为了在写代码之前理清思路，我举一个自己的例子：我有一个想法在SlideshowFX中开发一个新功能，此时我想开始写代码并直接实现它。但我知道我不是唯一一个对这个项目充满热情的开发人员。所以我的典型行为是这样的：1.编写以下类主体publicclassBurgersManager{}2.思考：“好吧，我应该在BurgersManager类中进行一些CRUD操作”3.编写：public...4.思考：“我应该返回什么值？目前void很好”5.publicvoidaddBurger(Burgerburger){//TODO稍后实现}public...6.思考：“我应该返回被吃掉的汉堡的实例吗？或者只是无效？就像第4步一样..."7.publicvoideat(Burgerburger,booleanfast){//TODO...8.告诉自己："糟糕，咖啡时间，我的咖啡在哪里...9.搜索，喝咖啡，和同事聊天10.然后告诉自己：“回去工作吧，我在做什么？”“我知道，你在这个例子中看到了你自己，对吧？在开始创作的时候，我们的思路有点乱，所以当你直接开始写代码的时候，那么代码也会很乱。在写代码之前考虑那个文档可以帮助你理清思路，明确你想用代码实现的事情的清单。所以第一步应该是写下面的代码：/***这个类通过提供CRUD操作来管理汉堡*采用单例模式。你可以使用{@link#getInstance()}获取此管理器的实例。*然后您可以使用以下方法来调用CRUD操作：*/{@link#addBurger(Burger)}用于添加Burger，由*单pieceExample;*@authorThierryWasylczenko*@version0.1*@sinceBurgerQueen1.0*/publicclassBurgersManager{}这是一个简短的例子，th这个例子可以：强迫你思考你创建的课程的目的是什么帮助你确定你的需求帮助你记住你在做什么，即使在你休息之后帮助你估计还需要什么做吧伙计们，你正在开发一个你可能不是单独工作的团队，你可能有你尊重的同事，你想和这些同事喝杯咖啡聊天。关键是，因为你喜欢他们，所以你想帮助他们参与到你激动人心的汉堡王实施中来。为此，最好的办法是确保他们在阅读您的代码时拥有完美的文档参考。即使他们在你写完两周后问你一个问题，你也会毫不犹豫地回答他们。这是文档很重要的另一个原因：它可以避免人们反复来找你并询问你的复杂算法是如何工作的，或者为什么在manager中添加的汉堡包没有被添加到workermanagergo中的统计数据中。在一个团队中，文档可以避免以下问题：工作时被打扰，难以返回工作；寻找可以回答问题的人，因为它可以让其他成员知道他们是否可以回答；等待团队成员有时间回答他们的问题。因此编写文档可以帮助团队提高工作效率并专注于开发。进一步取得成功是有点主观的。编写Javadoc给了我很大的成就感，因为当我再次使用我的API时，我编写代码时会参考文档，这有助于确保我不会忘记任何小细节。尽管我通常不会忘记，但很高兴知道有文档可以备份我的记忆。看到IntelliJIDEA显示我的文档让我有一种“嘿，看，我就像一个专业人士，我在做很棒的事情，我什至有文档”的感觉。在某种程度上这是真的，不是吗？因为当您使用log(Strings,inti)没有任何名称明确的参数描述的库时，您一定在想“这到底是什么？”像我这样的。我不知道您怎么想，但我认为新的Javadoc设计真的很酷。我认为保持文档清洁非常好。但正如我所说，这只是我的个人经历。编写Javadoc的技巧在Javadoc中，您可以使用这些不错的标签：@author@version@param@return@exception/@throws@see@since@serial/@serialField/@serialData@deprecated但本文的目的不是解释所有标签的详细信息，但作为文档作者和开发人员，我想分享我在编写Javadoc时使用的技术。使用@link和@linkplain指向一些代码在我的Javadoc中，如果存在依赖关系或对文档有用，我会提到其他类和方法。为了使浏览方法和类更容易，您可以使用@link。它是这样工作的：{@linkBurgersManager}指向一个类{@linkBurgersManagerburgersmanager}指向一个带有标签的类{@link#eat(Burger,boolean)}指向这个类中的一个方法{@link#eat(Burger,boolean)eat}指向这个类中的一个方法，带有标签{@linkBurgersManagers#eat(Burger,boolean)}指向另一个类中的一个方法{@linkBurgersManagers#eat(Burger,boolean)burgersmanagereat}的区别@link和@linkplain之间指向另一个标记类的方法是后者不会生成等宽代码。使用@code来指示代码段通常您会在Javadoc中找到一段代码，解释如何使用方法和类，或提供其他示例。要正确显示代码，并防止像这样的标记被破坏，您可以使用@code。{@codeListburgers=newArrayList<>();for(intindex=0;index<10;index++){burgers.add(newBurger("Burger#"+index));}}@code将为您生成标记。使用@value在文档中插入字段值当你有一个常量时，我??可能希望它的值显示在文档中。有两种选择：自己插入值。但是如果值改变了，你必须更新你的文档，如果你永远不会忘记，这是一个安全的选择；使用@value为您插入值，这样您就不必手动更新文档。对我来说，第二个选择是利用Javadoc工具的最佳方式，我将对此进行讨论。事实上，使用单个属性特别有用：/***该字段的默认值为{@value}。*该字段的默认值为{@value}。*/publicstaticfinalStringBURGER_SHOP_NAME="蒂埃里的商店”；但是你也可以指向其他常量，例如：/***该字段的默认值为{@value}当值*为57845349'>@link#OWNER}是{@value#OWNER}。*当*{@link#OWNER}是{@value#OWNER}。*/publicstaticfinalStringBURGER_SHOP_NAME="Thierry'sshop";/***这家很棒的汉堡店的默认所有者。*这家很棒的汉堡店的默认所有者。*/publicstaticfinalStringOWNER="Thierry";使用@since来指示此功能何时生效通常，在您的代码中，指示类或方法何时开始非常有用。为此，请使用@since标记，后跟版本/年份，该功能在以下位置实现：/***Thisawesomeclassisfordoingawesomethings*@sinceburger-core-0.1*@version0.2*/publicclassBurgersManager{/***允许吃汉堡*你可以吃汉堡*@sinceburger-core-0.2*/publicvoideat(Burgerburger,booleanfast){//TODO}}如您所见，我将其用于方法和类,并且不仅仅包括版本号。其实我们的应用现在有很多不同的模块，这些模块可以有不同的生命周期，也就是版本。说某个方法或类从0.2版本开始生效，没有什么特别的意思。那么0.2版本到底是什么？这就是为什么我总是使用相关的@since来帮助我的同事第一眼就了解这些事情何时生效。不仅如此，这个标签的好处之一是它可以帮助您创建发行说明。等一下，什么？不，这不像使用你最喜欢的IDE，比如IntelliJIDEA，并寻找包含“@sinceburger-core-0.2”的文件。瞧，您可以找到自该版本以来添加的所有方法和类。当然，这不会告诉您更新了哪些方法和类，只告诉您添加了什么。但是您应该看到这样一个简单的技巧有多么有用。不要匿名，使用@author我绝对讨厌的一件事是：开发人员不承认他们自己的代码，也没有表明他们编写代码的原因很糟糕。如果你写了一段代码，要么承认，要么成为经理。您可以使用@author来表明您是此类或方法的作者。我觉得最好把这个标签同时贴在类和方法上，因为一个类的方法不一定都是类的作者写的。另一个好习惯是包括方法或类的所有作者。想象一下，你和你的同事写了一个很棒的方法，标签表明你是这个方法的唯一作者。有一天你去度假，有人正在阅读你的方法，但不太理解它并想要一些细节。相反，因为您被标记为唯一作者，他们不知道可以从与您一起编写代码的同事那里轻松获得此信息。你知道我要说什么，对吧？记得在代码中加上@author来指明作者。对非void方法使用@return我会说这对我来说非常有意义。有时我看到像下面例子中的代码，我跪下了。/**获取地址。*@return*/publicStringgetAddress(){/*...*/}为什么！？说真的，你为什么不填写@return？“因为就一行，是为了获取地址。”不不不，请不要这样做。如果您这样回答，那是因为您的文档。怎么说呢，因为你的文档很差。是的，因为您可以轻松编写更好的版本，而不是上面看到的糟糕文档，请参阅：/***获取这家汉堡店的地址。地址格式如下：*{@code地址行1*地址行2*邮编城市}*@return这家汉堡店的地址不填则为{@codenull}*//**＊获取地址汉堡店。地址格式：*{@code地址行1*地址行2*邮编城市}*@return地址汉堡店，如果没有地址，返回{@codenull}.*/好多了，对吧？这样您的文档就会很有用。我一直在努力寻找一种合适的方法来记录代码，因为有时读者只阅读@return的内容，有时他们阅读@return的内容，您可以通过添加一些解释来避免混淆。有什么比使用@param来阐明参数的含义更令人沮丧的，而不是看到一个方法采用像i这样的模棱两可的参数而没有任何文档？有时你可以从方法名中猜出这个参数的用途，但有时你不能。所以在你的文档中，你应该使用@param来指明这个参数的含义，并描述可能的有效值。在我们的示例中，i可以是日志级别：INFO、DEBUG或TRACE。此标记有用的另一个示例是当值对应于索引时。在某些情况下索引从0开始，在某些情况下它从1开始。@param是用来描述这种差异的标签。生成文档在您的代码中包含文档是很棒的，但是现在您必须生成文档。所以你可以使用JDK提供的Java文档工具来生成它。通过执行这样的命令：javadoc{packages|source-files}[options]可以指定要生成文档的包名或文件名，多个名称之间用空格分隔。以下是jJavadoc工具接受的一些选项的简要说明：-author：在生成的文档中生成@author-d：在当前目录之外生成文档的目录-nodeprecated：不为标记为@的代码生成已弃用的文档-protected：包含受保护的和公共的类和类成员-private：包含私有类和类成员-public：仅包含公共类和类成员预览。一些依赖管理工具，如Maven和Gradle，也带有生成文档的阶段或任务。这很棒，因为您的文档始终可以在代码发布后立即生成，因此它始终是最新的。总结文档对您的整个团队来说非常重要。它可以帮助您弄清楚您正在编写什么代码，更重要的是，它可以帮助您了解为什么要按原样实现它。希望这篇文章让你想要编写更好的文档。如果是这样，请告诉我您是否编写了文档以及如何编写。给我发推文@twasyl，或在下方发表评论！
