Страница 1 из 2
Люди, пишушие код....
Добавлено: 27 дек 2005, 23:20
El Comandante
сабж.. скажите, в этой стране осталять в коде комментарии - это мегащедрость или что??? что по этому поводу говорит профессиональная этика? (больное)
Re: Люди, пишушие код....
Добавлено: 28 дек 2005, 00:28
Проф. Преображенский
El Comandante писал(а):сабж.. скажите, в этой стране осталять в коде комментарии - это мегащедрость или что??? что по этому поводу говорит профессиональная этика? (больное)
При чем тут страна? Давай уж сразу континент!
Судя по контексту, их тебе не оставили. Ну и ты не оставляй!
Зачем нарушать сложившиеся традиции?
Добавлено: 28 дек 2005, 05:13
Ursego
Оставляй для себя, будь хоть немного эгоистом. Вспоминается один оракловский SQL-файл: несколько скринов комментариев и одна строчка кода внизу.
Добавлено: 28 дек 2005, 11:23
Stanislav
Я всегда оставляю ровно столько, чтобы самому быстренько вспомнить, что я имел в виду (бывают сложнонавороченные алгоритмы)
а так вообще код самоочевиден
Re: Люди, пишушие код....
Добавлено: 28 дек 2005, 11:56
Marmot
El Comandante писал(а):сабж.. скажите, в этой стране осталять в коде комментарии - это мегащедрость или что??? что по этому поводу говорит профессиональная этика? (больное)
Профессиональная этика разрешает иметь полностью недокументированный код.
Это нормально, посмотрите например в код многих успешных open-source проектов.
По моим наблюдениям и личному опыту, коэффициент корреляции между качеством кода и количеством комментатиев равен нулю.
Я лично, предпочитаю self-documented code с правильным и описательными именами модулей, классов, методов и переменных.
При интенсивной иттеративной разработке комментари просто не успевают за изменениями в коде. Легче делать рефакторинг имён, IMO.
Добавлено: 28 дек 2005, 12:12
Zy
По-моему, документировать код нет никакого смысла. Разве что на это отпускают реальные деньги, и это делает не программист, который его писал, иначе эти комментарии скажут немного.
Надо иметь sequence diagramm'ы, особенно если приложение построенно на интерфейсах.
Если код написан правильно - то, с учетом понимания общей картины, там будет все понятно. Если код написан плохо - то и документация не сильно спасет.
Добавлено: 28 дек 2005, 12:25
Earl Grey
Я обычно помещаю общие структурные комментарии (так или иначе они появляются до того как куски получают детальную имплементацию).
Ну и обязательно всякие неочевидные вещи, типа
* вот здесь мы используем workarround потому что ...
* слева от "=" индекс i+1 (а не i, как справа) потому что ...
* всякие TBD
Ну и, конечно, селфдескриптив имена!
Добавлено: 28 дек 2005, 12:47
ajkj3em
Уникурсал Уникурсалыч писал(а):Ну и, конечно, селфдескриптив имена!
Код: Выделить всё
int a_loop_counter_that_is_incremented_by_1_comma_sometimes_by_2_or_4_comma_but_never_by_3;
была байка про то как какие-то вояки писали что-то там на фортране (по-моему) и у них компилятор валился с совершенно непонятной ошибкой. код они показывать не хотели, поэтому заняло прилично времени выяснить, что они буквально восприняли строчку в документации, где было написано, что мол длина имен переменных неограничена. ну ясный пень, что лимит был и они его превысили. лимит однако был 4096 символов.
Добавлено: 28 дек 2005, 13:00
El Comandante
Я немного перефразирую вопрос. Я имел в виду, в бОльшей степени, корпоративную культуру а именно привычку оставлять после себя хоть сколько нибудь читабельную документацию ( скажем по русски -"пояснительные записки"). Софт не есть конечный продукт компании сам по себе, речь идет о внутренней документации ( конфиденшл)
********* тут вырезал******
Добавлено: 28 дек 2005, 13:24
Marmot
El Comandante писал(а):Почему спросил - мне кажется у китайцев (в тч бананов) генетически заложена выживаемость ...
А у русских (украинцев, евреев, etc) значит генетически заложена вымираемость, так?
Ты уверен, что туда попал, а то мы тут о программировании говорим, а ты о китайцах.
Понаехали тут, расисты всякие...
Добавлено: 28 дек 2005, 13:38
El Comandante
А у русских (украинцев, евреев, etc) значит генетически заложена вымираемость, так?
Ты уверен, что туда попал, а то мы тут о программировании говорим, а ты о китайцах.
Понаехали тут, расисты всякие...
а что так нервно? Дело не в китайцах. я делюсь своими наблюдениями, не более того.
А у "русских (украинцев, евреев, etc)" в основном, не принято выжигать напалмом вокруг себя жизненное пространсто - так, на всякий случай. Я, наверное, сильно обощаю. Все - ИМХО
Добавлено: 28 дек 2005, 14:19
El Comandante
ОК, по сображениям политкорректности убрал упоминание о китайцах.
( видимо, некоторые после слова "китайцы" дальнейший текст не воспринимают)
Публично заявляю, что не имею ничего против них в целом.
Вопрос (третья попытка) - есть ли общие правила (традиции и тп) ведения внутренней проректной документации. Не отраслевые стандарты, а именно - общепринятые правила???
Добавлено: 28 дек 2005, 14:54
Vovchik
El Comandante писал(а):ОК, по сображениям политкорректности убрал упоминание о китайцах.
( видимо, некоторые после слова "китайцы" дальнейший текст не воспринимают)
Публично заявляю, что не имею ничего против них в целом.
Вопрос (третья попытка) - есть ли общие правила (традиции и тп) ведения внутренней проректной документации. Не отраслевые стандарты, а именно - общепринятые правила???
Нету. Ввиду полного осутствия документации как таковой. Коментарии тут пишут тока юниоры - и тока в течение первого года на первой работе программером.
Добавлено: 28 дек 2005, 16:17
vg
Скажу, что все и так знают.
1) То, что в одном случае полезно, в другом, как минимум трата времени, особенно, если код не очень. Так, что на сколько комментировать код - дело конкретного проекта, конкретной конторы и калче.
2) Почти во всех книжках-самоучителях по программированию говорится о полезности этого дела.
3) Некоторые комментарии могум быть полезными (в минимальном кол-ве) и для понятности и структурирования кода, где это надо. Если комент используется в этом ключе, то я предпочитаю, типа
ораыоалвы;
ывадлыдаод;
//
// То вверху и внизу - код
//
dsfsf; gfldd;gd ldfgdg;
lsdk;skf ;ldsksfl sdlkslf;
4) Пример, когда IDE позволяет по максимуму использовать коментарии, XML-подобные форматирования, #region ... #endregion и другие средства структурирования, включая возможности "разворачивание" и "сворачивание" текста кода - очень удобно, особено в языках, почти "чисто ООП" (там кода не меряно может быть в одном файле и по разному поводу) - это MS Visual Studio IDE.
5) Работал над проектом здесь в Канаде. Там "один файл" начинал один, вставлял другой, ремонтировал третий кулибин. Конечно, VSS помогает, но когда он оказывается бессильным перед человеческой глупостью - комментарии могут помочь.
6) Конечно должен быть разумный минимум пояснений и украшений.
Добавлено: 28 дек 2005, 16:18
Earl Grey
Vovchik писал(а):Коментарии тут пишут тока юниоры - и тока в течение первого года на первой работе программером.
Не обобщай!
У нас пишут спецификации разного уровня; data flow diagrams; installation protocols; readme; Installation guides etc.
Широко применяется практика Unit testing (с использованием NUnit) , дающая заодно практические образцы использования тех или иных компонентов.
Kонечно пишут не все, но ... не обобщай.