源代码注释样式：提示和最佳实践

花费大量时间在大型项目上的开发人员都了解代码注释的重要性。 当您在同一应用程序中构建许多功能时，事情往往会变得复杂。 数据位如此之多，包括函数，变量引用，返回值，参数……您希望如何保持？

无论是单独的项目还是团队项目，注释您的代码都是必不可少的也就不足为奇了。 但是许多开发人员并不知道如何进行此过程。 我已经概述了一些自己的技巧，可以创建整洁，格式化的代码注释 。 开发人员之间的标准和注释模板会有所不同，但是最终您应该努力使注释清晰易读，以进一步解释代码中令人困惑的区域。

我们应该开始讨论注释格式方面的一些差异。 这将使您更好地了解项目代码的详细程度。 之后，我将提供一些具体的提示和示例，您可以立即开始使用它们！

评论样式：概述

应该注意的是，提出的这些想法仅仅是对更清洁的评论的指导 。 各个编程语言均未针对如何设置文档提出准则或规范。

话虽如此，现代开发人员已经聚集在一起以格式化自己的代码注释系统。 我将提供一些主流样式，并详细说明它们的用途。

内联评论

实际上，每种编程语言都提供内联注释 。 这些仅限于单行内容，并且仅在特定点之后注释文本。 因此，例如在C / C ++中，您可以像这样开始内联注释：

// begin variable listing
var myvar = 1;
..

这对于将代码插入几秒钟以解释可能造成混淆的功能非常理想。 如果您要处理大量参数或函数调用，则可以在附近放置许多内联注释。 但是，最有益的用法是对小功能的简单说明 。

if(callAjax($params)) { // successfully run callAjax with user parameters
 ... code 
}

请注意，首先，所有代码都需要在左括号之后换行。 否则，所有内容都会被包含在同一注释行中！ 避免过度使用，因为通常不需要一直在页面上看到单行注释，但是特别是对于混淆代码中的结点，在最后一刻删除它们更容易。

描述块

当您需要包含大量解释时，通常只有一个衬里无法解决问题。 在编程的每个领域都有预格式化的注释模板。 在功能和库文件周围， 描述性块最为明显。 每当您设置新功能时，最好在声明上方添加一个描述性块 。

/**
  * @desc opens a modal window to display a message
  * @param string $msg - the message to be displayed
  * @return bool - success or failure
*/
function modalPopup($msg) {
...
}

上面是描述性函数注释的简单示例。 我大概已经在JavaScript中编写了一个名为modalPopup的函数，该函数需要一个参数。 在上面的注释中，我使用了类似于phpDocumentor的语法，其中每行前都有一个@符号，然后是一个选定的键。 这些都不会以任何方式影响你的代码，所以你可以写@description而不是@desc没有任何变化。

这些小键实际上称为注释标签 ，在网站上有大量记录。 随意编写自己的代码，并根据需要在整个代码中使用它们。 我发现它们有助于保持一切顺畅，因此我可以一目了然地查看重要信息 。 您还应该注意到我已经使用了/* */块样式的注释格式。 这将使所有内容都比在每行开头添加双斜杠更加整洁 。

小组/班级评论

除了注释功能和循环外，块区域的使用频率也不高。 真正需要强大的块注释的地方是后端文档或库文件的开头。 全力以赴，为您网站中的每个文件编写可靠的文档很容易-我们可以在WordPress等许多CMS中看到这种做法。

页面最上方的区域应包含有关文件本身的注释。 这样，您可以在同时处理多个页面时快速检查要编辑的位置 。 此外，您可以将该区域用作数据库中需要的最重要功能的数据库 。

/** 
  * @desc this class will hold functions for user interaction
  * examples include user_pass(), user_username(), user_age(), user_regdate()
  * @author Jake Rocheleau [email protected]
  * @required settings.php
*/
abstract class myWebClass { }

您可以看到，我只为伪造的myWebClass代码使用了一个小示例类。 我已经添加了一些元信息以及我的姓名和联系电子邮件地址 。 当开发人员编写开放源代码时，这通常是一个好习惯，因此其他人可能会与您联系以获得支持。 在较大的开发团队中工作时，这也是一种可靠的方法。

标签@required不是我在其他地方看到的东西。 我在一些项目中一直保持这种格式，仅在我自定义了许多方法的页面上。 每当将页面包含到文件中时，在输出任何代码之前，页面都必须出现。 因此，将这些细节添加到主类注释块中是记住所需文件的好方法。

前端代码注释

既然我们已经涵盖了3个重要的注释模板，让我们看看其他一些示例。 有许多前端开发人员已经从静态HTML转移到jQuery和CSS代码。 与编程应用程序相比，HTML注释的用途不那么明确，但是当您编写样式库和页面脚本时，随着时间的流逝，事情会变得一团糟。

JavaScript遵循一种更传统的注释方法，类似于Java，PHP和C / C ++。 CSS仅使用斜杠和星号划定的块样式注释 。 您应该记住，注释不会公开显示给您的访问者，因为CSS和JS都不会在服务器端进行解析，但是这两种方法都非常适合在代码中保留丰富的提示信息。

专门分解CSS文件可能很麻烦。 我们都熟悉在网上发表评论来解释Internet Explorer或Safari的修复程序。 但是我相信CSS注释可以在jQuery和PHP使用它们的级别上使用。 在深入探讨一些用于代码注释的技巧之前，让我们深入研究创建样式组。

CSS样式组

对于那些已经设计CSS多年的人来说，它几乎是第二自然。 您慢慢记住所有属性，语法，并为样式表构建自己的系统。 通过我自己的工作，我创建了所谓的分组，将相似CSS块配对到一个区域。

回到编辑CSS时，我可以在几秒钟内轻松找到所需的内容。 您选择的样式分组方式完全取决于您，这就是该系统的优点。 我有一些预设标准，下面概述了这些标准：

• @resets –删除默认的浏览器边距，填充，字体，颜色等。
• @fonts –段落，标题，块引用，链接，代码
• @navigation –主要的核心网站导航链接
• @layout –包装器，容器，侧边栏
• @header和@footer –这些可能会因您的设计而异。 可能的样式包括链接和无序列表，页脚列，标题，子导航

对样式表进行分组时，我发现标记系统可以提供很多帮助。 但是，与PHP或JavaScript不同，我使用单个@group标记，后跟类别或关键字。 我在下面提供了两个示例，以便您能理解我的意思。

/** @group footer */
#footer { styles... }

/** @group footer, small fonts, columns, external links **/

您也可以在每个注释块中添加一些额外的细节。 我选择使事情简单明了，以便样式表易于浏览。 评论全都与文档有关，因此只要您了解书面内容，那就好了！

更好的注释样式的4个技巧

我们已经在本文的前半部分研究了各种代码注释格式。 现在，让我们讨论一些使代码干净，有条理和易于理解的总体技巧。

1.保持一切可读

有时，作为开发人员，我们忘记了我们在写注释供人类阅读 。 我们了解的所有编程语言都是为机器构建的，因此将其转换为纯文本格式可能很繁琐。 重要的是要注意，我们不是在这里写大学水平的研究论文，而只是留下提示 ！

function getTheMail() {
	// code here will build e-mail

	/* run code if our custom sendMyMail() function call returns true
	   find sendMyMail() in /libs/mailer.class.php
	   we check if the user fills in all fields and message is sent! */
	if(sendMyMail()) { return true; // keep true and display onscreen success
    }
}

哪怕只是几个字总比没有好 。 将来当您回去编辑并处理项目时，常常会惊讶地发现您会忘记多少。 由于您并不是每天都在看相同的变量和函数名，因此您往往会慢慢忘记大部分代码。 因此，您永远不能留下太多评论 ！ 但是您可能会留下太多不好的评论。

作为一般的经验法则，请花一些时间在写作之前先停下来思考一下 。 问自己，该程序最令人困惑的地方是什么 ， 如何用“虚拟”语言最好地解释它 ？ 还要考虑一下为什么要完全按原样编写代码 。

当您忘记自定义（或第三方）功能的目的时，会弹出一些最令人困惑的错误。 如果这有助于您更轻松地记住功能， 请留下一条评论线索，引回其他几个文件 。

2.减轻空间！

我不能足够强调空格的重要性。 对于在拥有数百个文件的大型网站上工作的PHP和Ruby开发人员而言，这双双成真 。 您将整日盯着此代码！ 如果您可以浏览重要区域，那不是很好吗？

$dir1 = "/home/";                 // set main home directory
$myCurrentDir = getCurDirr();     // set the current user directory
$userVar = $get_username();      // current user's username

在上面的示例中，您会注意到我在每一行的注释和代码之间放置了额外的填充。 当您滚动浏览文件时，这种注释风格将显而易见 。 当变量块很干净时，它使查找错误和更正代码数百次变得容易 。

您可以在函数内部的代码上执行类似的任务，而对函数的工作方式感到困惑，但是此方法最终会使代码内联注释混乱，这与有序操作完全相反！ 我建议在这种情况下，在逻辑区域周围添加一个大的方框注释 。

$(document).ready(function() {
        $('.sub').hide(); // hide sub-navigation on pageload
		
        /** check for a click event on an anchor inside .itm div
              prevent the default link action so the page doesn't change on click
              access the parent element of .itm followed by the next .sub list to toggle open/close
        **/ 
		
        $('.itm a').live('click', function(e){
        e.preventDefault();
        $(this).parent().next('.sub').slideToggle('fast');
       });
});

这是针对子菜单滑动导航的少量jQuery代码。 第一个注释是内联的，以解释为什么我们隐藏所有.sub类。 在实时点击事件处理程序上方，我使用了块注释并将所有文字缩进到同一点 。 这使事情变得更漂亮，而不是冗长的段落，尤其是对于其他阅读您的评论的人。

3.编码时注释

加上适当的间距，这可能是最好的习惯之一。 在程序正常工作并记录每个程序之后，没有人希望回到过去。 我们大多数人甚至都不想回去记录这些令人困惑的地方！ 这确实需要很多工作。

但是如果在编码的时候可以写注释， 一切仍将是新鲜的 。 通常，开发人员会陷入困境，并在网上搜寻最简单的解决方案。 当您碰到尤里卡的时刻并解决了这样的问题时，通常会有一个清晰的时刻可以理解您以前的错误。 这将是留下关于您的代码的公开而诚实的注释的最佳时间 。

此外，这将使您习惯于注释所有文件。 在构建函数之后，回头弄清楚事物是如何工作所需的时间要大得多。 您未来的自我和您的队友都会感谢您提前发表评论 。

4.处理错误

我们不可能所有人都坐在电脑前几个小时来编写代码。 我想我们可以尝试，但是在某个时候我们需要睡觉！ 您可能需要在当天的代码中分道扬with，但某些功能仍然无法使用。 在这种情况下，至关重要的是，您要留下冗长而详细的评论，以免您遗漏了什么 。

即使经过一整夜的睡眠，您也可能会对重新进入编码的难度感到惊讶。 例如，如果您要构建图像上传页面而必须保留它未完成的位置，则应对您在流程中的何处发表评论 。 图像是否正在上传并存储在临时存储器中？ 或者，它们甚至在上传表单中都没有被识别，或者它们在上传后无法正确显示在页面上。

注释错误很重要，主要有两个原因。 首先，您可以轻松地从上次停下来的地方 重新尝试，并再次尝试解决问题 。 其次，您可以区分网站的实时生产版本和测试环境 。 请记住，应该使用注释来解释您为什么要做某事 ，而不是确切地做某事 。

结论

尽管很困难，但是开发Web应用程序和软件是一种令人满意的实践。 如果您是真正了解构建软件的少数开发人员之一，那么掌握您的编码技能就很重要。 从长远来看 ， 留下描述性评论只是一种好习惯 ，您可能永远不会后悔！

如果您有关于更清晰代码注释的建议，请在下面的讨论区中告诉我们！

翻译自: https://www.hongkiat.com/blog/source-code-comment-styling-tips/