站长百科 | 数字化技能提升教程 数字化时代生存宝典
首页
数字化百科
电子书
▼
建站程序
开发
服务器
办公软件
开发教程
▼
服务器教程
软件使用教程
运营教程
热门电子书
▼
CSS教程
WordPress教程
导航
程序频道
推广频道
网赚频道
人物频道
网站程序
网页制作
云计算
服务器
CMS
论坛
网店
虚拟主机
cPanel
网址导航
WIKI使用导航
WIKI首页
热点词条
最新资讯
网站程序
站长人物
页面分类
使用帮助
编辑测试
创建条目
网站地图
站长百科导航
站长百科
主机侦探
IDCtalk云说
跨境电商导航
WordPress啦
站长专题
网站推广
网站程序
网站赚钱
虚拟主机
cPanel
网址导航专题
云计算
微博营销
虚拟主机管理系统
开放平台
WIKI程序与应用
美国十大主机
编辑“
Gallery:编码标准
”(章节)
人物百科
|
营销百科
|
网赚百科
|
站长工具
|
网站程序
|
域名主机
|
互联网公司
|
分类索引
跳转至:
导航
、
搜索
警告:
您没有登录。如果您做出任意编辑,您的IP地址将会公开可见。如果您
登录
或
创建
一个账户,您的编辑将归属于您的用户名,且将享受其他好处。
反垃圾检查。
不要
加入这个!
==批注== All code should be well commented. Good comments explain why a code is written in a particular way. You don't need to explain how it works -- that much we can figure out from reading the code. The reasoning behind your choices is the interesting part. /* This is a good single line comment */ /* * This is a good block comment. Note how the * Open and closing comment tokens are on their own lines. */ // Bad -- no // style comments please. /* Bad block comments should have the open and closing * comment on their own line */ /* Worse. Block comments should have the open and closing * comment on their own line */ We prefer C-style block comments (/* */). USe of Perl/shell style comments (#) and C++ single line comments (//) are not allowed. Multiple line C style comments should see the asterisks aligned in a column (including the first line). In addition, commenting any tricky, obscure, or otherwise not-immediately-obvious code is clearly something we should be doing. Especially important to document are any assumptions your code makes, or preconditions for its proper operation. Any one of the developers should be able to look at any part of the application and figure out what's going on in a reasonable amount of time. ===分类/打包批注=== These should appear at the beginning of every file, and help to explain the purpose of the file, and its place in the Gallery hierarchy. For example, the Gallery's core module is named the GalleryCore package. Files in the classes directory are part of the Classes subpackage. When these comments apply to classes, they become the class comments. Such a comment might look like: /** * Short explanation (1 line!) * * Some more text which explains in more detail what * the file does and who might be interested * in understanding that. * * @version $Id: coding-standards.xml,v 1.6 2005/05/22 22:54:29 bharat Exp $ * @package GalleryCore * @subpackage Classes * @module GalleryModuleName */ *The first line should be short but meaningful. *The longer explanation may span several lines. Currently HTML markup is not retained, so try to avoid it. *An @author statement might be present. see function comments below for details. *The @version statement should be used unchanged. Subversion will magically transform this into the actual version info of the file. *The @package statement identifies the file with its package. *The @subpackage statement further classifies the file. *The @module statement gives the file a more meaningful name. Usually it should be the filename without the suffix .php. Dots are not allowed in the name, so convert them to underscore if needed. ===函数/方法批注=== These explain in detail what a function does, what parameters it expects and what is returned by the function. Function comments apply to classes as well, here they magically turn into method comments. Such a comment appears directly above a function definition looks like this: /** * Short explanation (1 line!) * * Some more text which explains in more detail what * the function does and who might be interested * in understanding that. * * @author Name <email address> * @author Name2 <other email address> * @param type description * @return type description */ function functionName( ... *The first line should be short but meaningful. *The longer explanation may span several lines. Currently HTML markup is not retained, so try to avoid it. *Use one @author statement per author, consisting of his/her name and optionally the email address in < and > signs. If given, the email address will be converted into a hyperlink automagically. *One or more @param statements describing the arguments the function expects. They must be given in the order in which they appear in the function definition. A @return statement, if the function returns something. ===分类变量及包括文件批注=== These are simple: They just quickly explain what a class varibale is used for, or what an included file does, or why we need it. These comments may be longer, if you have to explain more. They should appear just above the corresponding variable or include/require statement. They can be just one line and look like this: /** * Some explanation of the variable or file just below this comment. */ ===资料头=== All files should contain the following text in a form where it will not interfere with the purpose of the file (i.e., commented out). In this example, it's presented in a commented out form for inclusion into PHP files. <?php /* * Gallery - a web based photo album viewer and editor * Copyright (C) 2000-2006 Bharat Mediratta * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or (at * your option) any later version. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA. */ ?> ===特殊批注=== Occasionally you wind up checking in code that's not totally satisfactory. Sometimes this is inevitable. In order to locate these bits of code so that we find and resolve it later, use the following tags in a comment, above the code in question: *REVISIT: this is an optimization waiting to happen, or something that could be improved on later. Optionally. If we're bored. And have itchy C-x v v fingers. *TODO: this is missing functionality (so by definition, it's broken) that needs to be addressed at some point. *FIXME: this is stubbed/broken functionality, but I need to commit. It can limp for now. Keep in mind that you may not get back to this code for a while. You may not even be the one to fix the thing, so the more information that you provide while it's still fresh in your mind, the better. Potential solutions or workarounds are great, and may prove invaluable to whomever gets around to addressing the issue. If the comment isn't clear it may be ignored and eventually deleted. At some point in the future this will enable us to dictate the following: *No point release with FIXMEs *No major release with TODOs
摘要:
请注意,您对站长百科的所有贡献都可能被其他贡献者编辑,修改或删除。如果您不希望您的文字被任意修改和再散布,请不要提交。
您同时也要向我们保证您所提交的内容是您自己所作,或得自一个不受版权保护或相似自由的来源(参阅
Wordpress-mediawiki:版权
的细节)。
未经许可,请勿提交受版权保护的作品!
取消
编辑帮助
(在新窗口中打开)