WordPress:Commenting Code

Have you looked under the hood of a racing car lately? The bells and whistles inside are a nightmare to figure out. Remember the first time you looked at PHP, CSS, or HTML code? Bet that gave you a few moments of hysteria. When you are releasing your Themes and styles to the public, remember the user may take a peek under the hood and run screaming from the room, too.

你最近看过一辆赛车的车篷下面吗？那里的铃和汽笛，让人感觉就像是噩梦。还记得你第一次查看PHP, CSS, or HTML代码时候的感觉吗？我敢打赌，你几分钟内，都有种歇斯底里的感觉。当你公开发行你的主题和样式的时候，记住，用户可能深入地看到这些代码，而且会惊叫地在屋里奔跑。

评论代码是什么?

Comments or comment codes are part of code that helps the designer and the user figure out what is what, which section is which, and what is going on within the tangle of codes.

评论或者评论代码是代码的一部分，能够帮助设计人员和用户，了解每个部分是什么，以及各个部分在哪里，以及这些混乱的代码将会用于什么。

Comments in HTML or PHP pages (outside of the PHP code) look like this:

HTML或者PHP页面中的评论（PHP代码之外）看起来像：

<!-- comment here about what is going on -->

<!—在这里评论，最新发生的事 -->

Comments in CSS files look like this: CSS文件中的评论看起来像：

/* comment here about a style */

/* 在这里发表关于设计的评论*/

Comments inside of PHP code look like this: PHP代码之外的评论看起来像：

<?php the_excerpt(); // Show excerpt and not full post content ?>

<?php the_excerpt(); // 显示摘录而不是文章的全部内容?>

Or like this: 或者像：

<?php /* This is my special hack.
         It's so special it requires a comment that spans multiple lines! */

my_special_hack();
?>

<?php /* 这是我的特别的hack。
         这非常特别，需要跨越多行的评论！ */

my_special_hack();
?>

Tracking 模板文件

With the new modular template system with WordPress v1.5, CSS styles can cross files, so tracking down which section a reference is in within the code across template files can be frustrating, especially for someone unfamiliar with the code. It isn't a requirement, but it is helpful to add a comment to an opening div or class like this:

使用了WordPress1.5版本中新的模块模板系统，CSS样式可以跨越文件，在模板文件之间查找reference的哪个部分在代码中，可能不会成功，特别是那些不熟悉代码的人，更查找不到。这并不是必须的，但是能够帮助开启的div或者 class，添加评论，如：

<div id="sidebar"><!-- sidebar begins -->

<div id="sidebar"><!-- sidebar begins -->

Most people familiar with HTML and CSS would recognize that the id is the beginning of the section and a comment might not be needed, but wouldn't it be helpful if at the beginning of every WordPress Loop in every WordPress Theme was the comment:

输入HTML和CSS的人们，会了解id是一个部分的开始，而且可能需要评论，但是在每个WordPress 主题的每个WordPress Loop的开始部分，都是评论，就未必有用：

<!-- WordPress Loop begins here -->

<!-- WordPress Loop begins here -->

At the end of each div, especially those which cross template files, it would be nice to have an ending comment:

在每个div，特别是跨越模板文件的结尾部分，添加用于结束的评论，较好：

</div> <!-- end content -->

</div> <!-- end content -->

样式表中的评论

Some Themes include CSS inline styles in the header.php, index.php or single.php file, outside of the styles.css theme file.

有的主题在header.php, index.php 或者 single.php文件中包含了CSS inline 样式，在styles.css主题文件之外。

Typically, if someone is going to modify your carefully constructed and tested theme, there is a presumption that all of the style codes are in the style.css file. If you add any styles to an actual template file, please make a comment about it in the style.css so users know where to find it. There are few things more frustrating than trying to change a style without result, only to find the designer put the overriding style in the header of the actual file.

一般来说，如果有人想要更改你认真建构和测试的主题，假定所有的样式代码在style.css文件中。如果你向真正的模板文件添加了任何样式，请在style.css声明一下，这样用户知道在哪里找到这个样式。没有什么事情，比更改毫无结果的样式，更让人感到灰心丧气了，只会发现设计人员将最重要的样式放在 真正的文件的标头上。

Just add a short comment like: 添加一个简短的评论，如：

/* Styles for the header image are found within the header.php file. */

/* Styles for the header image are found within the header.php file. */

/*标头图像的样式在header.php文件中。*/

As important as it is to create the most wonderful and innovative design, it is also important to help the user use your design.

虽然创建惊奇创新的设计很重要，但是帮助用户使用这个设计，也是同样重要。

Commenting Out Code

There are times when you are testing template tags, plugin tags, or different bits of code and you need to prevent them from showing or intiating (being active). To do this, you "hide" them with comment codes. To restore their activation, just remove the comment code.

有时候，你正在测试模板标签, 插件标签，以及不同的代码，就不能够显示或者初始化（激活）代码。你需要使用评论代码"隐藏"这些代码。需要重新激活代码的时候，只要移除评论代码。

To hide or deactivate HTML:

要隐藏或者取消运行HTML：

<!-- <div class="redblock"><p>This is some HTML in
the redblock class.</p></div> -->

<!-- <div class="redblock"><p>这是redblock class的HTMl。</p></div> -->

To hide or deactivate CSS styles:

要隐藏或者取消运行CSS样式：

/* .redblock {font-size: 80%; font-style: italic; color: red; } */

/* .redblock {font-size: 80%; font-style: italic; color: red; } */

To hide or deactivate PHP code in a template file: 要隐藏或者使得模板文件中的PHP代码不活动：

<?php // the_content(Continue Reading...); ?>

or

<?php /* the_content(Continue Reading...); */ ?>

<?php // the_content(继续阅读...); ?>

或者

<?php /* the_content(继续阅读...); */ ?>