Люди, пишушие код....

[El Comandante]

сабж.. скажите, в этой стране осталять в коде комментарии - это мегащедрость или что??? что по этому поводу говорит профессиональная этика? (больное)

[Проф. Преображенский]

сабж.. скажите, в этой стране осталять в коде комментарии - это мегащедрость или что??? что по этому поводу говорит профессиональная этика? (больное)

При чем тут страна? Давай уж сразу континент!
Судя по контексту, их тебе не оставили. Ну и ты не оставляй! Зачем нарушать сложившиеся традиции?

[Ursego]

Оставляй для себя, будь хоть немного эгоистом. Вспоминается один оракловский SQL-файл: несколько скринов комментариев и одна строчка кода внизу.

[Stanislav]

Я всегда оставляю ровно столько, чтобы самому быстренько вспомнить, что я имел в виду (бывают сложнонавороченные алгоритмы)
а так вообще код самоочевиден

[Marmot]

сабж.. скажите, в этой стране осталять в коде комментарии - это мегащедрость или что??? что по этому поводу говорит профессиональная этика? (больное)

Профессиональная этика разрешает иметь полностью недокументированный код.
Это нормально, посмотрите например в код многих успешных open-source проектов.
По моим наблюдениям и личному опыту, коэффициент корреляции между качеством кода и количеством комментатиев равен нулю.
Я лично, предпочитаю self-documented code с правильным и описательными именами модулей, классов, методов и переменных.
При интенсивной иттеративной разработке комментари просто не успевают за изменениями в коде. Легче делать рефакторинг имён, IMO.

[Zy]

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

Надо иметь sequence diagramm'ы, особенно если приложение построенно на интерфейсах.

Если код написан правильно - то, с учетом понимания общей картины, там будет все понятно. Если код написан плохо - то и документация не сильно спасет.

[Earl Grey]

Я обычно помещаю общие структурные комментарии (так или иначе они появляются до того как куски получают детальную имплементацию).

Ну и обязательно всякие неочевидные вещи, типа

* вот здесь мы используем workarround потому что ...
* слева от "=" индекс i+1 (а не i, как справа) потому что ...
* всякие TBD

Ну и, конечно, селфдескриптив имена!

[ajkj3em]

Ну и, конечно, селфдескриптив имена!

Код: Выделить всё

int a_loop_counter_that_is_incremented_by_1_comma_sometimes_by_2_or_4_comma_but_never_by_3;

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

[El Comandante]

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

********* тут вырезал******

[Marmot]

Почему спросил - мне кажется у китайцев (в тч бананов) генетически заложена выживаемость ...

А у русских (украинцев, евреев, etc) значит генетически заложена вымираемость, так?

Ты уверен, что туда попал, а то мы тут о программировании говорим, а ты о китайцах.
Понаехали тут, расисты всякие...

[El Comandante]

А у русских (украинцев, евреев, etc) значит генетически заложена вымираемость, так?

Ты уверен, что туда попал, а то мы тут о программировании говорим, а ты о китайцах.
Понаехали тут, расисты всякие...

а что так нервно? Дело не в китайцах. я делюсь своими наблюдениями, не более того.
А у "русских (украинцев, евреев, etc)" в основном, не принято выжигать напалмом вокруг себя жизненное пространсто - так, на всякий случай. Я, наверное, сильно обощаю. Все - ИМХО

[El Comandante]

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

[Vovchik]

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

Нету. Ввиду полного осутствия документации как таковой. Коментарии тут пишут тока юниоры - и тока в течение первого года на первой работе программером.

[vg]

Скажу, что все и так знают.
1) То, что в одном случае полезно, в другом, как минимум трата времени, особенно, если код не очень. Так, что на сколько комментировать код - дело конкретного проекта, конкретной конторы и калче.
2) Почти во всех книжках-самоучителях по программированию говорится о полезности этого дела.
3) Некоторые комментарии могум быть полезными (в минимальном кол-ве) и для понятности и структурирования кода, где это надо. Если комент используется в этом ключе, то я предпочитаю, типа

ораыоалвы;
ывадлыдаод;

//
// То вверху и внизу - код
//

dsfsf; gfldd;gd ldfgdg;
lsdk;skf ;ldsksfl sdlkslf;

4) Пример, когда IDE позволяет по максимуму использовать коментарии, XML-подобные форматирования, #region ... #endregion и другие средства структурирования, включая возможности "разворачивание" и "сворачивание" текста кода - очень удобно, особено в языках, почти "чисто ООП" (там кода не меряно может быть в одном файле и по разному поводу) - это MS Visual Studio IDE.

5) Работал над проектом здесь в Канаде. Там "один файл" начинал один, вставлял другой, ремонтировал третий кулибин. Конечно, VSS помогает, но когда он оказывается бессильным перед человеческой глупостью - комментарии могут помочь.

6) Конечно должен быть разумный минимум пояснений и украшений.

[Earl Grey]

Коментарии тут пишут тока юниоры - и тока в течение первого года на первой работе программером.

Не обобщай!

У нас пишут спецификации разного уровня; data flow diagrams; installation protocols; readme; Installation guides etc.

Широко применяется практика Unit testing (с использованием NUnit) , дающая заодно практические образцы использования тех или иных компонентов.

Kонечно пишут не все, но ... не обобщай.