Насколько подробно документирован Ваш внутренний код?

[creative]

Привет всем!

Очень интересно узнать насколько подробно документирован код в Вашей компании, т.е. закрытый/проприетарный код.

Интересует степень подробности комментариев внутри исходного кода, а так же степень подробности документирования общей архитектуры проекта в вики Вашей компании и т.д.

[Sonic86]

Я документов о нашем коде вообще не видел.
Хотя у нас строго регламентирован стиль кодирования
У нас код относительно простой, но только если знать предметную область.
Комментарии пишутся к формам Delphi и к пакетам PL/SQL - обычно 2 строчки.
Проект в Вики документирован слабо, насколько мне известно.
В прикладных формах еще можно разобраться, а вот в более фундаментальных уже сложнее.
Я сам стараюсь оставлять комментарии к малопонятным функциям и процедурам, а если код сам пишу (не в своей компании), то комментирую почти все функции и процедуры. Хотя с другой стороны я почти не использую осмысленные имена переменных, а в компании так надо.

[MrD]

Sonic86 в сообщении #381595 писал(а):

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

Интересно, у меня точно поперек - комментариев оч мало, исхожу из того, что все можно понять по именам переменных/методов.

[Sonic86]

MrD писал(а):

:D Интересно, у меня точно поперек - комментариев оч мало, исхожу из того, что все можно понять по именам переменных/методов.

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

[Sanyok]

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

Я как-то подсчитал, что если продолжу программировать еще 70 лет и буду каждый день писать по 50 строк (в среднем быстрее писать не выходит, только если что-то совсем простое), то за всю жизнь напишу всего лишь около 1 млн 250 тыс. строк. То есть мне за всю жисть не написать программу эквивалентную по размеру бортовому ПО истребителя F-22 (кажется), написанному на Ada и состоящему где-то из 2 млн. строк.
Это я к тому, что на мой взгляд - дважды написанный один и тот же код - пустая трата времени и сил. Из-за этого меня очень бесит, когда я знаю, что уже писал что-то подобное, а работающий код потерял или стер. Поэтому я стараюсь свой код создавать по возможности универсальным и поподробнее комментировать (особенно процедуры и ф-ции - какие параметры они принимают, что делают и что возвращают).
На днях использовал код, который написал в 2002 или 2003 году (base64 кодирование/декодирование).
Так что имхо, надо документировать, по-возможности - на нормальном русском языке

[Portnov]

Sanyok в сообщении #401292 писал(а):

Так что имхо, надо документировать, по-возможности - на нормальном русском языке

s/русском/английском/
fixed.

[arseniiv]

На нормальном английском не все могут. И лучше написать на нормальном русском, чем на ненормальном английском! Хотя чаще они оба ненормальные, что уж поделать.

[Sanyok]

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

[arseniiv]

Да, мне тоже кажется, что трансилт даже с замечательного русского хуже даже плохого китайского!

[r-aax]

У нас обязательные: к каждому модулю, функции, параметрам функции. Остальное опционально.

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

И вообще, комментариев много не бывает. Пожалейте людей, которые будут работать с вашим кодом.

[creative]

В nginx кстати комментариев почти нет, тем не менее в его коде можно разобраться без труда (правда если привыкнуть к наименованиям).

Может быть комментарии писать только к ключевым функциям и структурам и нетривиальным местам кода?

[Sanyok]

creative в сообщении #401398 писал(а):

Может быть комментарии писать только к ключевым функциям и структурам и нетривиальным местам кода?

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

[Ed_Em]

creative в сообщении #381577 писал(а):

Очень интересно узнать насколько подробно документирован код в Вашей компании, т.е. закрытый/проприетарный код.

Поубивал бы любителей проприетарщины.
// сам все, что пишу, выкладываю под GPL. Комментирую как можно больше - чтобы самому потом меньше ломать голову над позапрошлогодним кодом :)