Как лучше комментировать код?

@Alex_Mio · Регистрация: 13.02.2008

Студворк — интернет-сервис помощи студентам

Здравствуйте. У меня есть вопросы по коментированию кода.
1. Какой язык лучше использовать для коментариев (русский или английский)?
2. Нужно ли коментировать действие каждой строки (вплоть до "I++ // увеличение значения i")?
3. Где лучше располагать коментарии: в коде или справа от кода?

@J.Smith · 25.07.2008, 19:25

Мне кажется надо коментировать так, чтобы код был легко понятен автору (или группе авторов), чтобы через пару месяцев можно было спокойно вспомнить что к чему. Поэтому все сугубо индивидуально. Только на счет пункта 2. Зачем каждую строку коментировать то? Тогда точно нечитабельно будет, да и программа раза в полтора тяжелее получится.

@mik-a-el · 25.07.2008, 19:50

Сообщение от Alex_Mio

1. Какой язык лучше использовать для коментариев (русский или английский)?

На языке разработчика.

Сообщение от Alex_Mio

2. Нужно ли коментировать действие каждой строки (вплоть до "I++ // увеличение значения i")?

Нет. Комментировать нужно суть алгоритмов, что делают функции и т.п. Комментирвоание очевидных вещей лишь замусоривает код.

Сообщение от Alex_Mio

3. Где лучше располагать коментарии: в коде или справа от кода?

Над строкой кода - так они лучше читаются.

@Lurker · 25.07.2008, 19:58

ИМХО коментировать нужно осмысленные куски... например:
цикл для расчёта точности
а вот тут мы вычисляем Лямбду
так-же неплохо подписать для хранение чего используются переменные
коментарии лучше распологать справа, если не мешают длинные строки кода

@CheshireCat · 27.07.2008, 00:19

Рекомендую читать: Ален И. Голуб, "Веревка достаточной длины, чтобы выстрелить себе в ногу". Имеется в электронном виде, Гугл в помощь.

@mik-a-el · 27.07.2008, 00:37

Сообщение от CheshireCat

Рекомендую читать: Ален И. Голуб, "Веревка достаточной длины, чтобы выстрелить себе в ногу".

http://www.cyberguru.ru/progra... rules.html
http://www.cyberguru.ru/progra... ules2.html

@Pricolist · 28.07.2008, 10:32

некоторые куски кода написаны не самостоятельно и если пришлось затратить время на осмысление того что они делают, то в следующий раз можно сократить это время прочитав коментарий по данному коду.

@Alex_Mio · 28.07.2008, 18:26 **[ТС]**

Спасибо за ответы и советы.
Еще я одну штуку заметил, что когда в структуре закомментировал некоторые переменные (комме нтарии находились справа от переменных), то когда я писал их в программе потом, рядом высвечивался комментарий. Это характерно только для Visual C++ 6.0 или и для других сред тоже?

@Spo1ler · 04.08.2008, 23:33

хм, лично я бы писал комментарии на английском, комментировал сверху, потому что горизонтальная прокрутка не рулит. ну и каждую строку комментировать далеко не обязательно, а то это больше смахивает не на комментирование, а на маразм.

@Барра Белый Гепард · 04.08.2008, 23:49

Вообще комментарии должны быть лаконичны, понятны и не банальны. Код должен быть самодокументирующимся.
Пример 1.

Code
1
public void sdghndfhj(); // Резко прячет окно в трей.

или

Code
1
public void bossComes();

или

Code
1
public void emergensyHide();

Первое явно не правильно, второе поймёте только вы, третье - пожалуй правильно.
В общем мысль такая - совершенно непонятный код комментарии не прояснят.

@Vit@L · 05.08.2008, 06:48

Я считаю что коменнтировать выражения подобные i++ или ++i смысла нет. А вот если ты используешь такие переменные как a, b, x, y. То их желательно пояснить, т.е. указать что означает x и y. Потому что если этого не сделать, то ты сам через несколько месяцев не сможешь разобраться в своей же проге. Ну, а вообще, лично я стараюсь давать осмысленные имена переменным и константам. К примеру в переменной где, хранится сумма, я обзываю ее как Summa.

@Барра Белый Гепард · 05.08.2008, 16:38

Точно. Только, если знаете английский, то транслита следует избегать. Мне однажды сказали добавить фичу в программку. Так её, оказалось её написали своим транслитом, и переменные, и комментарии, китайцы. "Незабываемые очучения"

@Spo1ler · 05.08.2008, 21:57

помоему в программах вообще надо писать все на английском, все таки я придерживаюсь стороны opensource. а язык опенсорса это английский

Vourhey · 05.08.2008, 22:38

Spo1ler, полностью согласен. Это стандарт де-факто.

@CheshireCat · 06.08.2008, 10:17

Язык комментариев (английский или другой) зависит от степени владения этим языком программиста. Увы, приходилось встречать такиииие! комментарии на английском, что - лучше бы их не было вовсе.
Так что - зависит от.

Vourhey · 06.08.2008, 14:52

Как говорится, пусть комментарий будет написан неграмотно, но он будет. Английским сейчас должен владеть любой программист (на уровне чтения и написания текстов точно), независимо от того, в какой области он работает.

@cyBEERkotleta · 18.09.2023, 18:01

Мне кажется, комментарии в коде в основном излишни. Код должен пояснять сам себя и не нуждаться в комментариях. Скажем так, документирующие комментарии иногда помогают. Но только если они позволяют читать код лучше, а не объяснять его. Всего можно добиться хорошими именами и архитектурой программы.

@vantfiles · 18.09.2023, 18:14

Сообщение от Vourhey

Английским сейчас должен владеть любой программист

Вы читали комментарии китайцев? Да, они на английском. Угу.

У каждой функции, у каждого класса должна быть шапка - ее удобнее писать сверху.
Отдельные тонкие места в теле ф-ции лучше писать сбоку.

А в целом:

Сообщение от cyBEERkotleta

Код должен пояснять сам себя и не нуждаться в комментариях.

бесспорно, но. Это для Вас Ваш код является понятным. Работаете в команде - будьте любезны пояснять тонкие моменты.

@Shamil1 · 19.09.2023, 01:09

1. Нужен комментарий в начале файла с описанием, для чего предназначен модуль (или класс). Это нужно для того, чтобы тот, кто будет позже вносить в него изменения (в том числе и сам автор), не добавил туда метод, которому там не место.

2. Нужны комментарии в начале каждой экспортируемой функции (или каждого публичного метода)... при условии, что разработчик может их увидеть, не открывая файл с кодом (как, например, /// в C#). Но это должно быть прописано в правилах оформления кода, принятых в вашей организации. Если кто-то пишет такие комментарии, а кто-то нет, то смысл теряется.

3. Нужны комментарии для неочевидных частей кода.
Например, вы кодируете малоизвестный алгоритм и у вас есть подозрения, что будущий читатель может не догадаться, что этот код делает и, вообще, почему он работает (даёт правильный ответ). Если написать название алгоритма, то читатель при желании сможет найти его описание и разобраться.
Или, например, вы применили некий хак для нейтрализации бага во внешней библиотеке. Или усложнили код ради производительности.
Или даже то, о чём можно догадаться, но не сразу.

Добавлено через 1 минуту
Язык комментариев определяется корпоративными правилами.

@Mikhaylo · 24.09.2023, 18:39

Немало копий сломано, немало рекомендаций написано по поводу того, как правильно комментировать код.

Но я для себя вывел одну простую концепцию, когда прорабатывал свой язык разработки Концепт абстрактного языка разработки Рафинад

Комментарии - это информация, в первую очередь, об окружении кода и лишь во вторую очередь - это комментирование самого кода.

Тут требуется раскрытие понятия "окружение кода". Код, в конечном итоге, имплементируется и работает в некоторой системе и взаимодействует с её составными частями (микропроцессор, память, сетевые интерфейсы, базы данных, видеокарты и прочие периферийные устройства, пользователи, администраторы, сетевая инфраструктура здания и т.д.). Всё это я и называю окружением кода.

1. Когда смотришь на код, ты его видишь как есть, комментарии в принципе не так критичны. В этом смысле я понимаю комментарии как заголовки, которые помогают быстро ориентироваться в портянке кода. Это code comments.

2. В коде нет информации о том, в какой среде он запускается или может запускаться. Надо понимать, что любой разработчик примерно представляет, в какой среде этот код будет запускаться, например, это ноутбук с Linux или какой-то сервер с Windows. Но ведь бывают конфигурируемые многопользовательские системы, в которых не так просто разобраться! Надо комментировать код в тех моментах, где предполагаются какие-то особенные моменты окружающей среды кода, например, "этот принтер не воспринимает букву Ё, поэтому заменяем на Е". Это environment comments.

И вот теперь становится понятнее:
1. Code comments
2. Environment comments

У этих двух видов комментариев разные подходы.

И если вы пишете библиотечный код, то следует понимать, что окружением кода являются достаточно произвольные hardware/software, поэтому следует описывать системные требования (аппаратные характеристики железа, версии программного обеспечения) и назначение библиотечного кода, ибо непонятно, зачем был написан код в отрыве от конкретных железяк и софта.

Отдельный разговор про комментирование окружения в прошлом и будущем (цели и описание движения к цели). Так появляются depricated и to do в комментариях.

Ничего нового не сказал, просто обобщил и систематизировал как следует.

Новые блоги и статьи Все статьи Все блоги /
Символьное дифференцирование igorrr37 13.02.2026 / * Логарифм записывается как: (x-2)log(x^2+2) - означает логарифм (x^2+2) по основанию (x-2). Унарный минус обозначается как ! */ #include <iostream> #include <stack> #include <cctype>. . .	Камера Toupcam IUA500KMA Eddy_Em 12.02.2026 Т. к. у всяких "хикроботов" слишком уж мелкий пиксель, для подсмотра в ESPriF они вообще плохо годятся: уже 14 величину можно рассмотреть еле-еле лишь на экспозициях под 3 секунды (а то и больше),. . .	И ясному Солнцу zbw 12.02.2026 И ясному Солнцу, и светлой Луне. В мире покоя нет и люди не могут жить в тишине. А жить им немного лет.	«Знание-Сила» zbw 12.02.2026 «Знание-Сила» «Время-Деньги» «Деньги -Пуля»
SDL3 для Web (WebAssembly): Подключение Box2D v3, физика и отрисовка коллайдеров 8Observer8 12.02.2026 Содержание блога Box2D - это библиотека для 2D физики для анимаций и игр. С её помощью можно определять были ли коллизии между конкретными объектами и вызывать обработчики событий столкновения. . . .	SDL3 для Web (WebAssembly): Загрузка PNG с прозрачным фоном с помощью SDL_LoadPNG (без SDL3_image) 8Observer8 11.02.2026 Содержание блога Библиотека SDL3 содержит встроенные инструменты для базовой работы с изображениями - без использования библиотеки SDL3_image. Пошагово создадим проект для загрузки изображения. . .	SDL3 для Web (WebAssembly): Загрузка PNG с прозрачным фоном с помощью SDL3_image 8Observer8 10.02.2026 Содержание блога Библиотека SDL3_image содержит инструменты для расширенной работы с изображениями. Пошагово создадим проект для загрузки изображения формата PNG с альфа-каналом (с прозрачным. . .	Установка Qt-версии Lazarus IDE в Debian Trixie Xfce volvo 10.02.2026 В общем, достали меня глюки IDE Лазаруса, собранной с использованием набора виджетов Gtk2 (конкретно: если набирать текст в редакторе и вызвать подсказку через Ctrl+Space, то после закрытия окошка. . .

@Alex_Mio 1 / 1 / 1 Регистрация: 13.02.2008 Сообщений: 18

	Как лучше комментировать код? 25.07.2008, 19:18. Показов 10298. Ответов 33 Метки нет (Все метки) Здравствуйте. У меня есть вопросы по коментированию кода. 1. Какой язык лучше использовать для коментариев (русский или английский)? 2. Нужно ли коментировать действие каждой строки (вплоть до "I++ // увеличение значения i")? 3. Где лучше располагать коментарии: в коде или справа от кода? 0

@J.Smith Кто вы, мистер Смит? 285 / 117 / 2 Регистрация: 03.03.2008 Сообщений: 525
	25.07.2008, 19:25
	Мне кажется надо коментировать так, чтобы код был легко понятен автору (или группе авторов), чтобы через пару месяцев можно было спокойно вспомнить что к чему. Поэтому все сугубо индивидуально. Только на счет пункта 2. Зачем каждую строку коментировать то? Тогда точно нечитабельно будет, да и программа раза в полтора тяжелее получится. 0

@Lurker 6140 / 1898 / 14 Регистрация: 07.07.2008 Сообщений: 10,417
	25.07.2008, 19:58
	ИМХО коментировать нужно осмысленные куски... например: цикл для расчёта точности а вот тут мы вычисляем Лямбду так-же неплохо подписать для хранение чего используются переменные коментарии лучше распологать справа, если не мешают длинные строки кода 0

@CheshireCat 2924 / 1274 / 114 Регистрация: 27.05.2008 Сообщений: 3,465
	27.07.2008, 00:19
	Рекомендую читать: Ален И. Голуб, "Веревка достаточной длины, чтобы выстрелить себе в ногу". Имеется в электронном виде, Гугл в помощь. 0

@Pricolist сам себе админ и инженер 1345 / 99 / 11 Регистрация: 07.09.2006 Сообщений: 1,573
	28.07.2008, 10:32
	некоторые куски кода написаны не самостоятельно и если пришлось затратить время на осмысление того что они делают, то в следующий раз можно сократить это время прочитав коментарий по данному коду. 0

@Alex_Mio 1 / 1 / 1 Регистрация: 13.02.2008 Сообщений: 18
	28.07.2008, 18:26 [ТС]
	Спасибо за ответы и советы. Еще я одну штуку заметил, что когда в структуре закомментировал некоторые переменные (комме нтарии находились справа от переменных), то когда я писал их в программе потом, рядом высвечивался комментарий. Это характерно только для Visual C++ 6.0 или и для других сред тоже? 0

@Spo1ler 296 / 56 / 5 Регистрация: 22.05.2008 Сообщений: 788
	04.08.2008, 23:33
	хм, лично я бы писал комментарии на английском, комментировал сверху, потому что горизонтальная прокрутка не рулит. ну и каждую строку комментировать далеко не обязательно, а то это больше смахивает не на комментирование, а на маразм. 0

@Vit@L Кратк. - сест. тал. 87 / 51 / 4 Регистрация: 13.03.2008 Сообщений: 543
	05.08.2008, 06:48
	Я считаю что коменнтировать выражения подобные i++ или ++i смысла нет. А вот если ты используешь такие переменные как a, b, x, y. То их желательно пояснить, т.е. указать что означает x и y. Потому что если этого не сделать, то ты сам через несколько месяцев не сможешь разобраться в своей же проге. Ну, а вообще, лично я стараюсь давать осмысленные имена переменным и константам. К примеру в переменной где, хранится сумма, я обзываю ее как Summa. 0

@Барра Белый Гепард 0 / 0 / 0 Регистрация: 04.08.2008 Сообщений: 8
	05.08.2008, 16:38
	Точно. Только, если знаете английский, то транслита следует избегать. Мне однажды сказали добавить фичу в программку. Так её, оказалось её написали своим транслитом, и переменные, и комментарии, китайцы. "Незабываемые очучения" 0

@Spo1ler 296 / 56 / 5 Регистрация: 22.05.2008 Сообщений: 788
	05.08.2008, 21:57
	помоему в программах вообще надо писать все на английском, все таки я придерживаюсь стороны opensource. а язык опенсорса это английский 0

Vourhey Почетный модератор 7393 / 2639 / 281 Регистрация: 29.07.2006 Сообщений: 13,696
	05.08.2008, 22:38
	Spo1ler, полностью согласен. Это стандарт де-факто. 0

@CheshireCat 2924 / 1274 / 114 Регистрация: 27.05.2008 Сообщений: 3,465
	06.08.2008, 10:17
	Язык комментариев (английский или другой) зависит от степени владения этим языком программиста. Увы, приходилось встречать такиииие! комментарии на английском, что - лучше бы их не было вовсе. Так что - зависит от. 0

Vourhey Почетный модератор 7393 / 2639 / 281 Регистрация: 29.07.2006 Сообщений: 13,696
	06.08.2008, 14:52
	Как говорится, пусть комментарий будет написан неграмотно, но он будет. Английским сейчас должен владеть любой программист (на уровне чтения и написания текстов точно), независимо от того, в какой области он работает. 0

@cyBEERkotleta 8 / 5 / 3 Регистрация: 17.02.2022 Сообщений: 27
	18.09.2023, 18:01
	Мне кажется, комментарии в коде в основном излишни. Код должен пояснять сам себя и не нуждаться в комментариях. Скажем так, документирующие комментарии иногда помогают. Но только если они позволяют читать код лучше, а не объяснять его. Всего можно добиться хорошими именами и архитектурой программы. 0

@Shamil1 Модератор 3134 / 2281 / 469 Регистрация: 26.03.2015 Сообщений: 8,879
	19.09.2023, 01:09
	1. Нужен комментарий в начале файла с описанием, для чего предназначен модуль (или класс). Это нужно для того, чтобы тот, кто будет позже вносить в него изменения (в том числе и сам автор), не добавил туда метод, которому там не место. 2. Нужны комментарии в начале каждой экспортируемой функции (или каждого публичного метода)... при условии, что разработчик может их увидеть, не открывая файл с кодом (как, например, /// в C#). Но это должно быть прописано в правилах оформления кода, принятых в вашей организации. Если кто-то пишет такие комментарии, а кто-то нет, то смысл теряется. 3. Нужны комментарии для неочевидных частей кода. Например, вы кодируете малоизвестный алгоритм и у вас есть подозрения, что будущий читатель может не догадаться, что этот код делает и, вообще, почему он работает (даёт правильный ответ). Если написать название алгоритма, то читатель при желании сможет найти его описание и разобраться. Или, например, вы применили некий хак для нейтрализации бага во внешней библиотеке. Или усложнили код ради производительности. Или даже то, о чём можно догадаться, но не сразу. Добавлено через 1 минуту Язык комментариев определяется корпоративными правилами. 0

@Mikhaylo 698 / 574 / 75 Регистрация: 20.09.2014 Сообщений: 3,712
	24.09.2023, 18:39
	Немало копий сломано, немало рекомендаций написано по поводу того, как правильно комментировать код. Но я для себя вывел одну простую концепцию, когда прорабатывал свой язык разработки Концепт абстрактного языка разработки Рафинад Комментарии - это информация, в первую очередь, об окружении кода и лишь во вторую очередь - это комментирование самого кода. Тут требуется раскрытие понятия "окружение кода". Код, в конечном итоге, имплементируется и работает в некоторой системе и взаимодействует с её составными частями (микропроцессор, память, сетевые интерфейсы, базы данных, видеокарты и прочие периферийные устройства, пользователи, администраторы, сетевая инфраструктура здания и т.д.). Всё это я и называю окружением кода. 1. Когда смотришь на код, ты его видишь как есть, комментарии в принципе не так критичны. В этом смысле я понимаю комментарии как заголовки, которые помогают быстро ориентироваться в портянке кода. Это code comments. 2. В коде нет информации о том, в какой среде он запускается или может запускаться. Надо понимать, что любой разработчик примерно представляет, в какой среде этот код будет запускаться, например, это ноутбук с Linux или какой-то сервер с Windows. Но ведь бывают конфигурируемые многопользовательские системы, в которых не так просто разобраться! Надо комментировать код в тех моментах, где предполагаются какие-то особенные моменты окружающей среды кода, например, "этот принтер не воспринимает букву Ё, поэтому заменяем на Е". Это environment comments. И вот теперь становится понятнее: 1. Code comments 2. Environment comments У этих двух видов комментариев разные подходы. И если вы пишете библиотечный код, то следует понимать, что окружением кода являются достаточно произвольные hardware/software, поэтому следует описывать системные требования (аппаратные характеристики железа, версии программного обеспечения) и назначение библиотечного кода, ибо непонятно, зачем был написан код в отрыве от конкретных железяк и софта. Отдельный разговор про комментирование окружения в прошлом и будущем (цели и описание движения к цели). Так появляются depricated и to do в комментариях. Ничего нового не сказал, просто обобщил и систематизировал как следует. 0