我们只需4/30即可调整Futureestack注册。条款和条件适用。 现在注册

文档作为代码,在新遗物代码中的文档

6分钟阅读
func(c *命令)run()(字符串,错误){//设置locale blaaargh

- 我们的源代码中的旧评论

软件由单词组成。一些单词,例如UI文本或命令行消息,适用于人机交互;一些,如API调用和错误代码,目标其他软件;有些表单是文档自述文件,用户指南,在线帮助等。

但是,软件中绝大多数单词是其源代码:使其运行的那些单词。

代码也包含人类可读文本。考虑任何软件:无论编程语言如何(除外)棕榈树及其深奥的同伴),机会是您在来源中发现了大量有意义和有用的单词:

  • 嵌入式参考文档,可用于自动构建文档(例如,GODOC,Javadoc,GraphQL和OpenApi)
  • 字符串文字,从日志消息到输入提示的错误
  • 配置文件中的示例和注释
  • 名字CLI命令,变量,函数和方法
  • 在源代码中的评论(就像上面引用的那样)

现在我们已经使我们的软件开源,我们代码中的文档的想法对我们来说更加重要。

当代码中的单词被遗忘时

如果未记录代码,则不存在。在许多情况下,代码可能缺少嵌入式文档,使开发人员难以理解它是如何运作的或者旨在使用。

但这并不是唯一可能出错的东西:未记录的API模式导致用户在加载到API资源管理器时的用户体验差;没有注释的配置文件很难调整,并且错误地错误可以使不必要的困难进行故障排除。当软件缺乏嵌入式文档时,充实会出错。

在一天结束时,我们的软件也通过其单词的质量来衡量,它对用户说话的方式以及它记录的方式。伟大的文档开锁一个伟大的开发人员体验。如果我们希望我们的Dev社区能够提取我们的代码并丰富它,我们应该确保它得到很好的评论和记录。

产品语言团队如何在代码中为文档做出贡献

如果我详细介绍我们的工作,那么这里有一个很长的博客帖子,所以这里是产品语言团队完成的典型文档工作的最新例子:

  1. 为准备开源释放基础设施代理人,我们在代码注释中介绍了Typos,格式化问题,禁止单词和敏感信息的整个代码库。与此同时,我们在CLI和调试消息中修复了大写问题和语法,并编辑了自述文件。
  2. 我们经常编辑nerdgraph graphql.模式嵌入式文档。模式中的文档是良好的GraphQL体验的关键;例如,参见下面的屏幕截图:所有字段都具有基本的参考文档。这同样适用于REST API的OpenAPI规范。记录的内网架构的示例
  3. 我们还在样本配置文件中编辑评论,帮助用户更快地安装我们的代理和集成。这示例配置文件为了Windows服务集成例如,提供了一个简短的解释,即在现有文档上构建,使得用户急剧仍然可以获得一些指导,即使他们跳过我们的文档也可以获得一些指导。
    #要包含服务,请创建要应用于服务名称的过滤器列表。#查找与任何匹配列表匹配的服务。默认情况下,#没有服务。###当前,仅支持WindowsService.Name元数据进行过滤。#prepend“正则表达式”以指示模式是正则表达式。#include_matching_entities:windowsservice.name:# - 正则表达式“^ * $”# - “servicenametobeincluded”

帮助我们在代码中进行文档

我们致力于为我们的开源项目带来明确,简洁,周到的文件 - 从我们的代理商到新的遗物一个应用程序对我们开源开发人员网站。

如果您对您的代码中遇到的文档有任何疑问或需求,请不要犹豫,在适当的回购中向我们提供评论或拉动请求。

快乐的文档 - 作为编码!