海外社媒SNS代运营Tiktok代运营公司
Revive Old Posts

写代码很像写散文。 每个人的做法都略有不同,因此,当我们阅读代码时,每个人都有不同的声音。 我们有不同的命名约定和不同的问题解决逻辑。 我们都认为我们的代码有意义——特别是如果它有效——但其他人可能不会。 为了解决这个问题,我们都需要在源代码注释方面做得更好。 这样,项目旁边的任何人都将有一个清晰的路径来理解和改进/修复我们的代码。

如何评论代码——基础知识

首先,让我们确保我们都在关于评论的内容的同一页面上。 在本文中,我们将讨论脚本本身中的内嵌注释。 例如,在 CSS 文件中,可读代码被处理器忽略的注释分解。


/** Body Element Styling **/

body {color:red;}

h1 {size:17px;}


/** Sidebar Widget Styling**/

#email-signup-1 {text-transform:uppercase;}

每种编程语言在源代码中都有不同的注释方式。 PHP 和 HTML 以及 JavaScript 和 C# 的开始和结束代码符号都略有不同。 虽然也有一些特定于语言的实践,但有更多的共享。

我们将讨论您在自己使用时会遇到的一些不同类型的评论、它们的用途和最佳实践(或者可能只是养成的好习惯)。

注释代码的基本原则很简单:

  • 使它们简短
  • 保持它们的相关性
  • 大量使用它们,但不要过度使用

如果你能记住这些,你会做得很好。

讨论反对者的时刻

非常简单,让我们谈谈源代码评论反对者。 有不少开发人员认为,对您的代码进行评论应该是非常罕见的情况。 当您需要源代码注释时,这表明您的代码在某些方面很薄弱。 你的命名约定、逻辑或其他东西并不像它应该的那样透明。

而且,公平地说,这个论点有一定的道理。 但是,无论您的代码编写得多么好和分解得多么好,都存在许多情况,这些情况足以证明以注释的形式包含文档。

海外社媒SNS代运营Tiktok代运营公司

主要的问题是,您并不总是参与该项目的工作,而且您无法保证下一个人的经验如何。 即使您编写了出色的代码,也可能会出现混淆和歧义。

标题块文档

如果您查看一些文件,代码不会立即开始,因为文件中有一个很大的标题,描述了它的用途、变量、函数、方法等。 他们甚至可能在它周围的一个巨大盒子里引起你的注意。

这不是一个好习惯。 因为这有点毫无意义。 嗯,这真的毫无意义,实际上。

注释代码的最佳实践

另外,看看上面的例子:评论标题太长了。 有 非常 很少有理由这样做。 所以不要。

您将放入该文件的任何内容 应该 无论如何都要放入您的文档中。 将它放在评论中是多余的。 此外,最终用户可能永远不会进入您的源代码,因此只有其他开发人员(或已经了解文档的软件的核心用户)才能看到评论。

另外,无论何时文档发生变化,您都必须在该文件中进行更改。 很容易错过一个步骤,然后您的代码库可能会严重混乱。

标题注释何时有用

标题注释在源代码中非常有用,可以简单解释该文件中的预期内容。 比如,这是一个游戏开发引擎自带的脚本,叫做RPG Maker,控制每个游戏场景的核心JS文件是这样开头的:


//=============================================================================
// rpg_scenes.js v1.6.2
//=============================================================================

//=============================================================================

/**
 * The Superclass of all scenes within the game.
 * 
 * @class Scene_Base
 * @constructor 
 * @extends Stage
 */
function Scene_Base() {
    this.initialize.apply(this, arguments);
}

Scene_Base.prototype = Object.create(Stage.prototype);
Scene_Base.prototype.constructor = Scene_Base;


此外,请注意版本号列在最顶部。 做这个。 但是,请勿提供文件更改和新版本发布日期的完整列表。 它记录在 Git 或其他版本控制软件中,任何需要该信息的人都应该可以使用它。 对于大多数查看此文件的人来说,版本号已经足够了。

在线文档

最常见的源代码注释类型是内嵌注释。 在正确地做、过火或对它们过于节俭之间有一个很好的界线。 这是一种平衡,你必须随着时间的推移学习,但有一些很好的经验法则需要考虑。

不要逐行注释。 在线评论是一回事。 逐行注释使代码看起来几乎不可读。 见下文:



function sourceCodeComment () { //calls a function
  var comment = document.getElementbyID("Code Comment").value; // declares a variable
  if (comment != null && comment != '') {  //starts an if statement to evaluate if there's a comment
        return console.log("Thank you for your comment.") //prints a string to the console
}


那是矫枉过正。 如果必须,请在函数之前或之后执行。 但不是每一行。 它很突兀,而且通常没有帮助。 函数(或元素)前的注释有利于组织和清晰。 更重要的是应该进入文档。

如果你觉得有必要记录,这样的事情就足够了。


//checks to see if there's a comment. If so, returns a thank you message.

function sourceCodeComment () {
  var comment = document.getElementbyID("Code Comment").value; 
  if (comment != null && comment != '') { 
        return console.log("Thank you for your comment.")
}


反对者会提到,即使是这种注释也是多余的,因为函数、变量和方法的良好命名约定将使代码可读。 这在一定程度上是正确的,但是如果您要将歧义保持在绝对最低限度,那么快速评论是一种可行的方法。

在源代码注释中放置警告是可以的

有时,显而易见的问题解决方案并不能真正解决问题。 在这些情况下,在开发后期进入项目的开发人员可能会查看文件并考虑重构它 明显的 解决方案。 这样做将完全是浪费时间。

或者也许将来会出现其他事情,他们试​​图调用一个破坏一切并使项目陷入困境的函数。

无论如何,如果您知道某些事情实际上是行不通的,并且您知道其他人将来可能会尝试,那么警告他们是可以的。


// Don't bother trying to use goodCodeComment() here. 
// It breaks bestPractices() despite seeming like the best option.
// We went with simplyOkayCodeComment() instead.

function simpleOkayCodeComment() {
	//some kind of code goes here
}


另外,你注意到我们在那个例子中做了什么吗? 我们不仅向未来的开发人员发出警告,还在函数中间添加了占位符注释。 因为源代码注释被忽略,所以您可以使用它们在文件中保留占位符文本(有点像对自己的注释返回那里,或者作为一个例子给某人作为解释)。

不要做混蛋

我以前见过这种情况,特别是在没有很好控制的开源项目中。 有人会发现一段不太出色的代码片段并使用评论来贬低作者。


//This function looks like it was written by a third grader.
//It shouldn't work, but it does somehow. I don't want
//to fix it because I want you all to see how bad it is.


或者也许他们确实修复了代码,但包含了代码,只是注释掉了,这样他们就可以炫耀他们的代码,同时嘲笑以前的作者。


//The old code was so bad, I just had to leave it here for you to see.
//I fixed it. My code is below. But look at this.

// function theMatrix() {
//	var neo = maybeTheOne.data + theOracle.data
//	if theOne() !== neo
//		return console.log("you got the gift, but it looks like you're waiting for something")
// }


只要确保你永远不会这样做。 即使你认为你很有趣或者它让你看起来很好,它不是,也不是。

WordPress花园建议你也读一下这篇文章  如何使用 WordPress Issuu 嵌入块

注释掉代码的真正用途是让您在尝试其他东西时保持代码方便。 或者举一个例子,说明以前什么不起作用,所以有人不会徒劳地再试一次。

WordPress 的源代码注释

一般来说,WordPress 以四种不同的语言运行。 HTML、CSS、PHP 和 JavaScript。 确保为注释使用正确的字符是必不可少的。

对于 HTML:

<!-- comments go here and can be single or on multiple lines --></em>

在 CSS 中:

/* Any number of lines will be a comment until the comment is closed */ 

PHP 和 JavaScript 都有相同的方法来处理单行和多行注释:

<?php function(); // a single line comment is like this ?>

或者

<?php /* unlike above, you can carriage return
				and no matter how many lines you use,
					the comment won't stop until closed */

结论

如果您日复一日地在战壕中编写代码并推送到 GitHub,那么您的组织可能会有他们希望您遵循的评论的样式指南。 但是,如果他们不这样做,或者您是一个人,记住这些东西不仅会使您将来的工作更轻松,而且还会帮助任何跟随您的人。

您有什么提示和技巧可以充分利用代码注释?

Skillup/shutterstock.com 提供的文章特色图片

海外社媒SNS代运营Tiktok代运营公司
Revive Old Posts