Комментирование кода

При написании любого кода нужно делать комментарии, обязательно и по-любому. В любых случаях, не зависимо от типа работ: «для себя» или для коммерческого заказа. Вы ещё 5, а может и 10 раз вернётесь к коду, написанный несколько месяцев или лет назад и уже забытый. Даже самая лучшая память на свете не заменит самый плохой карандаш. Главный критерий комментирования - если блок кода занимает больше 5 строк или имеет вложенный скрипт, тогда обязательно делаем пометки.

 Особые случаи, требующие написания продуманных комментариев - комментирование работы функции ( что вернёт и какие у неё параметры писать обязательно). Вот пример моего комментирования функции, написанной на PHP, которая заменяет в дробном числе точку на запятую (в PHP дробная часть отделяется от целой точкой, но пользователь не поймёт что к чему, поэтому нужно сделать замену. заменить точку на запятую можно стандартной функцией «number_format» или написать свою функцию).

/*
***************************************************************************************** 
	Функция: заменяет точку в дробном числе на запятую
	Вернёт:  число-строку с запятой
 	Параметры: $a - дробное число
*****************************************************************************************
*/
function point2zap($a)
{ 
	$a=(string)$a;
 	$len=strlen($a);
 	for($i=0; $i<$len; $i++)
 	{ 
 		if($a[$i]=='.')
 		{ 
 			$a[$i]=',';
 			$i=$len; 
 		} 
 	}
 	return $a; 
}

или вот

/*
***************************************************************************************** 
	Функция: возвращает значение TRUE если текущий пользователь является
 			 зарегистрированным пользователем (турфирмой), FALSE - в противном случае. 
 	Параметры: 
 				$type - тип пользователя (значения: 1 - зарегистрированный пользователь,
 				2 - турфирма, 3 - администратор) 
*****************************************************************************************
*/
function privileges($type)
{

Теперь перейдём к технической части комментариев, к тому как их объявить.

HTML

<!-- Текст комментария -->

CSS

/* 
	ещё один комментарий. текст можно писать в несколько строк. 
*/

PHP, Java Script, C++

/* 
	конструкция для многострочных комментариев 
*/

// пример однострочного комментария

SQL

/* 
	конструкция для многострочных комментариев 
*/

-- текст, идущий после двух минусов (--), будет являться комментарием

Delphi

{ 
	конструкция №1 для многострочных комментариев 
}

(* 
	конструкция №2 для многострочных комментариев 
*)

// пример однострочного комментария