Перейти из форума на сайт.

НовостиФайловые архивы
ПоискАктивные темыТоп лист
ПравилаКто в on-line?
Вход Забыли пароль? Первый раз на этом сайте? Регистрация
Компьютерный форум Ru.Board » Компьютеры » Прикладное программирование » Комментирование кода

Модерирует : ShIvADeSt

 Версия для печати • ПодписатьсяДобавить в закладки
Страницы: 1 2 3

Открыть новую тему     Написать ответ в эту тему

KADABRA



Великий покусатель
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
Кто как комментирует свой код, что пишете в комментариях?
Используете ли ПО для генерации документации из комментариев?
 

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


----------
Это не подпись.

Всего записей: 1718 | Зарегистр. 14-07-2003 | Отправлено: 21:18 08-08-2006
murkovich



Advanced Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
Это же очень индивидуально, для разных людей, разных типов программ.  
Если для себя пишешь, то в комментарах пишешь то, чего можешь потом забыть. Если для заказчика/работодателя - то в зависимости от условий. Всякие вещи, которые неочевидны для не-тебя. И уж точно не следует писать вещи типа "увеличиваем счетчик на 1".

Всего записей: 1551 | Зарегистр. 26-05-2005 | Отправлено: 21:39 08-08-2006
TheChampion

Advanced Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
Да, doxygen
 
Коментарий идет перед функцией, изредка перед группой функций, поясняя, что происходит. Иногда коментарии внутри кода, если используется что-то хитровыдуманное.
 
Вообще стараюсь писать так, чтобы поменьше коментировать. Хороший код не требует обильных объяснений :-)

Всего записей: 656 | Зарегистр. 25-06-2004 | Отправлено: 23:48 08-08-2006
FuzzyLogic



Advanced Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
Комментирую довольно много, обычно сначала блок перед функцией, и потом понемногу дописываю к концам строк.  По поводу того что "Хороший код не требует обильных объяснений" позволю не согласиться, всё зависит от предметной области, для некоторых вещей это и действительно не нужно, но я мне частенько приходится писать модели различных физических процессов, там где одних уравнений и формул на книгу в n-дцать листов, уж не говоря про код, так без комментариев черт ногу сломит если потом захочется что-то поправить.

Всего записей: 1920 | Зарегистр. 27-07-2002 | Отправлено: 01:11 09-08-2006
TheChampion

Advanced Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
FuzzyLogic
Зависит от разных факторов. Если математику писать в стиле C, то без коментария сам черт ногу сломит, это факт. Писал я как-то параллельную штуку на MPC, там была система из 4 уравнений, а всего было 6 решеток. Код вычислений имел прямоугольную форму и размеры 80х60 строк
 
А если писать на C++, то не будешь же ты коментировать вот здесь каждую строчку:

Код:
int simple_iterations(matrix& A, vector& b, vector& x, double prec)
{
  vector x1 = x;
  int steps = 0;
  do
  {
    x = A * x1 + b;
    ++steps;
  }
  while(abs(x - x1) >= prec);
  return steps;
}

Всего записей: 656 | Зарегистр. 25-06-2004 | Отправлено: 12:37 09-08-2006
WiseAlex



Софтовых дел М...
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
TheChampion

Цитата:
А если писать на C++,

действительно объектно-ориентированные системы требуют меньше комментариев
KADABRA
в качестве примеров лучше посмотреть Code Complete макконела и Refactoring фаулера. Это будет и авторитететно и менее субъективно.
--
Я пишу комментарии в неочевидных местах, но если быть честным эти места можно сделать намного более очевидными применяя рефакторинг и подбирая более удачные идентификаторы.

Всего записей: 1001 | Зарегистр. 02-03-2003 | Отправлено: 13:20 09-08-2006
unikum



Junior Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
Коментирую в теле, когда начинается какой то логический блок, типа  
//  ======= Делаем то, то, для того то ===========
Потом, когда листаеш гораздо быстрее находится нужное место.
 
Относительно "хороший код не требует обильных объяснений" немного не согласен поскольку со временем забывается практический смысл написанного. То что он делает вроде понятно, но зачем просто забывается, а это ой как напрягает когда ищишь багу или место для новой фичи в коде, который писал пол года назад.  
 
И еще, я активно не пользуюсь, но есть куча программ, которые на основе коментариев в исходниках делают хелпины. Очень помогает знаети ли, когда можно сгенерить хелпину по классу и посмотреть что там наваяли и что еще нужно добавить.

Всего записей: 106 | Зарегистр. 23-07-2006 | Отправлено: 13:23 09-08-2006
Maxer



Gold Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
без комментариев, даже копирайты не ставлю, ибо на это времени много уходит..
я обычно "пишу", а не пишу...

----------
красный феррари

Всего записей: 5225 | Зарегистр. 04-05-2004 | Отправлено: 14:33 09-08-2006
Mickey_from_nsk

Advanced Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
Склоняюсь к тезису "хороший код лучше коментария". У Джоэла была на эту тему хорошая статейка. Важнее правильно дать имена переменным и функциям (методам) и правильно организовать систему функций. Когда функцию (или метод) делать для логического действия а не для того "чтобы не дублировать код в 10 местах".
С другой стороны, в неочевидных местах (или местах, с которыми редко сталкиваешься) лучше все-таки пояснить, что там происходит. Как пример, работал через SNMP с Cisco, а там протокол был заковыристый. Для общего понимания коментарии были просто необходимы, иначе через неделю уже ничего не понимал, т.к. не был спецом в этом протоколе. Благо модуль написан и забыт.

Всего записей: 636 | Зарегистр. 21-10-2002 | Отправлено: 15:09 09-08-2006
xlebopezka

Junior Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
Стараюсь ставить комментарии везде, где начинается новый логический участок кода.
Как правило короткое объяснение, что делается на этом участке, иногда, для чего он нужен (т.е. в этом случае комментарий больше относится не к коду, а к логике  работы самой программы).

Всего записей: 93 | Зарегистр. 06-07-2005 | Отправлено: 16:26 09-08-2006
OldGopher



Silver Member
Редактировать | Профиль | Сообщение | ICQ | Цитировать | Сообщить модератору
Комментарии внутри функций ставлю исключительно для себя.  
 
Как-то меня выкинули с одной конторы, ну, а потом долго разбирались в моем коде.  
Попросили помочь... Я им и помог, за деньги...
 
Время такое: найти б/м толкового начальника проще, чем толкового инженера...

Всего записей: 3802 | Зарегистр. 25-10-2001 | Отправлено: 10:13 10-08-2006
Xarde



Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
OldGopher, не понимаю я таких как ты. Если твой код непонятен остальным членам команды, то это минус в первую очередь тебе. Особенно в условиях
Цитата:
Время такое: найти б/м толкового начальника проще, чем толкового инженера...  

Извини, если неверно понял ситуацию и твой код другие не смогли прочесть по причине крайней неумности последних.
 
От себя скажу, что ленив чрезмерно и ставлю комментарии там, где без них не понять, что (а чаще - зачем) делается. Правда, для того, чтобы таких моментов было как можно меньше, приходится правильнее именовать переменные, классы и функции.

Всего записей: 266 | Зарегистр. 06-07-2003 | Отправлено: 11:37 10-08-2006
RedPromo



Full Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
Да без коментов никак пишу коменты только там где непонятен или сложен код.  Хотя хоть и плохо это но допустим по 1С не люблю вобще коменты писать.  А вобще без коментов однозначно плохо потом будет, я на практике это проходил поначалу вобще не писал потом пару раз покопался в коде и получил жизненый урок.

Всего записей: 558 | Зарегистр. 05-04-2006 | Отправлено: 17:48 11-08-2006
kukabarra



Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
комментарии пишу редко. все равно их потом не читаю
 
основное использование // и ## - закомментировать старый код, перед написанием нового - на случай отката (знаю что version control лучше )
 
если код сложный - лучше нарисовать в визио схему, где все гораздо более наглядно и понятно, чем в комментах (главное не забывать ее обновлять, чтоб не устарела к чертям)

Всего записей: 232 | Зарегистр. 14-07-2005 | Отправлено: 03:09 14-08-2006
Yurkov_VV



Newbie
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
Ставлю комментарий перед каждой функцией.
А вообще руководствуюсь вот этим http://www.opennet.ru/docs/RUS/coding_standard/

Всего записей: 24 | Зарегистр. 06-10-2005 | Отправлено: 10:20 14-08-2006
basilevs

Junior Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
IMHO. Комменты нужны или перед внешней функцией, или в месте, где делаются неочевидные вещи, порождённые потребностью эффективности кода. Также комменты нужны при недописанном коде.
Вообще написание должно начинаться с краткого изложения о реализации.

Всего записей: 161 | Зарегистр. 09-12-2004 | Отправлено: 13:43 14-08-2006
kukabarra



Member
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
basilevs
Цитата:
Также комменты нужны при недописанном коде.

 
при недописанном коде нужны FIXME и TODO (и IDE, которая их сама находит и показывает). от просто "комментов" там толку мало.

Всего записей: 232 | Зарегистр. 14-07-2005 | Отправлено: 16:29 14-08-2006
whungry

Newbie
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
Yurkov_VV
 
  А ссылочка-то, того, как бы это по-интеллигентнее, малоупотребима.
  Там ведь всё больше об организации и претворении в жизнь процесса комментирования и ведения man'ов, а не о подходах к самому процессу. Этакий партминимум для руководителя, а не приёмы для исполнителя.
  Кстати, сам "дизайн" этого документа - его же лучшая антиреклама.
  На мой взгляд и вкус, разумется.
 

Всего записей: 9 | Зарегистр. 11-05-2006 | Отправлено: 21:37 14-08-2006
kly



Newbie
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору
У меня похоже на "стиль" Xarde
Пишу, где требуется пояснить, почему сделано именно так, а не иначе.

Всего записей: 9 | Зарегистр. 19-06-2006 | Отправлено: 12:30 15-08-2006
Yurkov_VV



Newbie
Редактировать | Профиль | Сообщение | Цитировать | Сообщить модератору

Цитата:
А ссылочка-то, того, как бы это по-интеллигентнее, малоупотребима.

В каком смысле?

Цитата:
Там ведь всё больше об организации и претворении в жизнь процесса комментирования и ведения man'ов, а не о подходах к самому процессу

Значит плохо читал, т.к. там описывается весь процесс с форматированием кода.

Цитата:
Кстати, сам "дизайн" этого документа - его же лучшая антиреклама.  

А ты что на красоту смотришь или на содержание?

Всего записей: 24 | Зарегистр. 06-10-2005 | Отправлено: 17:26 15-08-2006
Открыть новую тему     Написать ответ в эту тему

Страницы: 1 2 3

Компьютерный форум Ru.Board » Компьютеры » Прикладное программирование » Комментирование кода


Реклама на форуме Ru.Board.

Powered by Ikonboard "v2.1.7b" © 2000 Ikonboard.com
Modified by Ru.B0ard
© Ru.B0ard 2000-2024

BitCoin: 1NGG1chHtUvrtEqjeerQCKDMUi6S6CG4iC

Рейтинг.ru