Как правильно писать комментарии к программе
Забавно, уже в который раз пишу статью исходя из того, по каким поисковым запросам ко мне попадают люди. И сегодня гвоздь нашей программы гугл со своим запросом Комментарии в программировании, начнем
“Всегда пишите комментарии к своим программам,” - это написано в любом учебнике. Только вот почему-то ни в одном я еще не увидел информации о том, как именно их писать. Ну что ж попытаемся разобрать все “по полочкам”
/*
* Copyright (c) 2006-2007 Erin Catto http://www.gphysics.com
*
* This software is provided 'as-is', without any express or implied
* warranty. In no event will the authors be held liable for any damages
* arising from the use of this software.
* Permission is granted to anyone to use this software for any purpose,
* including commercial applications, and to alter it and redistribute it
* freely, subject to the following restrictions:
* 1. The origin of this software must not be misrepresented; you must not
* claim that you wrote the original software. If you use this software
* in a product, an acknowledgment in the product documentation would be
* appreciated but is not required.
* 2. Altered source versions must be plainly marked as such, and must not be
* misrepresented as being the original software.
* 3. This notice may not be removed or altered from any source distribution.
*/
package Box2D.Dynamics{
import Box2D.Common.Math.*
import Box2D.Common.*
import Box2D.Collision.*
import Box2D.Collision.Shapes.*
import Box2D.Dynamics.*
import Box2D.Dynamics.Contacts.*
import Box2D.Dynamics.Joints.*
public class b2World
{
..........................................................
public function DrawShape(shape:b2Shape, xf:b2XForm, color:b2Color, core:Boolean) : void{
var coreColor:b2Color = s_coreColor;
switch (shape.m_type)
{
case b2Shape.e_circleShape:
{
var circle:b2CircleShape = (shape as b2CircleShape);
var center:b2Vec2 = b2Math.b2MulX(xf, circle.GetLocalPosition());
var radius:Number = circle.GetRadius();
var axis:b2Vec2 = xf.R.col1;
m_debugDraw.DrawSolidCircle(center, radius, axis, color);
if (core)
{
m_debugDraw.DrawCircle(center, radius - b2Settings.b2_toiSlop, coreColor);
}
}
break;
case b2Shape.e_polygonShape:
{
var i:int;
var poly:b2PolygonShape = (shape as b2PolygonShape);
var vertexCount:int = poly.GetVertexCount();
var localVertices:Array = poly.GetVertices();
//b2Assert(vertexCount <= b2_maxPolygonVertices);
var vertices:Array = new Array(b2Settings.b2_maxPolygonVertices);
for (i = 0; i < vertexCount; ++i)
{
vertices[i] = b2Math.b2MulX(xf, localVertices[i]);
}
m_debugDraw.DrawSolidPolygon(vertices, vertexCount, color);
if (core)
{
var localCoreVertices:Array = poly.GetCoreVertices();
for (i = 0; i < vertexCount; ++i)
{
vertices[i] = b2Math.b2MulX(xf, localCoreVertices[i]);
}
m_debugDraw.DrawPolygon(vertices, vertexCount, coreColor);
}
}
break;
}
}
..........................................................
public var m_destructionListener:b2DestructionListener;
public var m_boundaryListener:b2BoundaryListener;
public var m_contactFilter:b2ContactFilter;
public var m_contactListener:b2ContactListener;
public var m_debugDraw:b2DebugDraw;
public var m_positionIterationCount:int;
// This is for debugging the solver.
static public var s_enablePositionCorrection:int = 1;
// This is for debugging the solver.
static public var s_enableWarmStarting:int = 1;
// This is for debugging the solver.
static public var s_enableTOI:int = 1;
};
Это код файла b2World.as из библиотеки Box2D. Собственно это пример того, как программу комментировать не надо (не в обиду ее разработчикам, чистое ИМХО). Вы поняли что-нибудь? Вот именно.
Во-первых - “шапка”. Само собой в ней должны быть реквизиты программиста в виде его ФИО и сайта (ну или e-mail, если нет сайта), но вот полный текст лицензии лучше в каждый файл не вписывать. Вполне достаточно строчки типа “under LGPL2.1″ и ссылки на соответствующую страницу GNU Project. К тому же не помешает информация о том, что это вообще за файл, что он делает и зачем нужен.
Во-вторых всегда пишите, для чего нужен тот или иной класс, что делает та или иная функция, какие параметры она принимает. Тут есть много подходов (кому интересно, гуглим по запросам “Qt style comments”, “JavaDOC style comments” и т.д.), сам я не пользуюсь никакими парсерами, поэтому пишу как-то так
//Some info about this class. For example: It's realy good class 
class GoodClass{
//GoodClass constructor
public function GoodClass {
liveIsGood = true;
}
/* Set liveIsGood variable
* isit: new value of liveIsGood variable
*/
public function setIsLiveGood(isit:boolean):void{
if (isit){
liveIsGood = isit;
}else{
trace("Вася, ты не прав");
}
}
public var liveIsGood:boolean; //Is the live a good thing?
}
В-третьих отделяйте каждый логический кусок длинного кода, например
..........................................................
// Display the options page
function ljxp_display_options() {
global $wpdb;
// List all options to load
$option_list = array( 'ljxp_host' => 'www.livejournal.com',
'ljxp_username' => '',
'ljxp_password' => '',
'ljxp_custom_name_on' => false,
'ljxp_custom_name' => '',
'ljxp_privacy' => 'public',
'ljxp_comments' => 0,
'ljxp_tag' => '1',
'ljxp_more' => 'link',
'ljxp_community' => '',
'ljxp_skip_cats' => array(),
'ljxp_header_loc' => 0, // 0 means top, 1 means bottom
'ljxp_custom_header' => '', ); // I love trailing commas
// Options to be filtered with 'stripslashes'
$option_stripslash = array('ljxp_host', 'ljxp_username', 'ljxp_custom_name', 'ljxp_community', 'ljxp_custom_header', );
foreach($option_list as $_opt => $_default){
add_option($_opt); // Just in case it does not exist
$options[$_opt] =(in_array($_opt, $option_stripslash) ? stripslashes(get_option($_opt)) : get_option($_opt)); // Listed in $option_stripslash? Filter : Give away
// If the option remains empty, set it to the default
if($options[$_opt] == '' && $_default !== ''){
update_option($_opt, $_default);
$options[$_opt] = $_default;
}
}
..........................................................
Это кусок кода из плагина ljCrossposter. Думаю, идея ясна, хотя я предпочитаю делать так (кто не в курсе, делается INS’ом)
<?php
//First block-------------------------------
//Hear a long-long code
//Second block------------------------------
//Hear a long-long code too
?>
Ну и еще два момента. Если вы планируете, что этот код увидите не только вы, пишите его на английском (хотя у меня была ситуация, когда пришлось по настоянию заказчика переводить все комментарии в своей программе на русский ) и используйте интернациональные сокращения:
- FIXME. Проблемный код или некрасивый хак, который следует исправить
- NOTE. Пояснение мест, где легко можно допустить ошибки
- TODO. Планируется расширение функционала в этом месте
- XXX. Что-то типа “Эта хрень вроде работает, но непонятно как и в каких случаях”
Ну вроде все, если что упустил, пишите в комментариях.
26.06.2008 в 00:47
Мне еще ООП предстоит освоить )) Зато коменты писать уже умею, благодаря вам.
Спасибо за статью.
26.06.2008 в 11:56
Если хотите научится “думать в стиле ООП”, то советую Ruby или Python (первое предпочтительней ИМХО)