2014 dxdy logo

Научный форум dxdy

Математика, Физика, Computer Science, Machine Learning, LaTeX, Механика и Техника, Химия,
Биология и Медицина, Экономика и Финансовая Математика, Гуманитарные науки




 
 Насколько подробно документирован Ваш внутренний код?
Сообщение29.11.2010, 01:11 
Аватара пользователя
Привет всем!

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

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

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

 
 
 
 Re: Насколько подробно документирован Ваш внутренний код?
Сообщение23.12.2010, 22:41 
Sonic86 в сообщении #381595 писал(а):
Я сам стараюсь оставлять комментарии к малопонятным функциям и процедурам, а если код сам пишу (не в своей компании), то комментирую почти все функции и процедуры. Хотя с другой стороны я почти не использую осмысленные имена переменных, а в компании так надо.

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

 
 
 
 Re: Насколько подробно документирован Ваш внутренний код?
Сообщение24.12.2010, 07:42 
MrD писал(а):
:D Интересно, у меня точно поперек - комментариев оч мало, исхожу из того, что все можно понять по именам переменных/методов.

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

 
 
 
 Re: Насколько подробно документирован Ваш внутренний код?
Сообщение17.01.2011, 23:02 
Аватара пользователя
Я всегда и комменты пишу, и стараюсь давать всем сущностям (классам, методам, переменным, ф-ям) осмысленные имена. Причем чем больше область видимости переменной, тем длиннее делаю имя. Если нечто является константой - то ее имя все целиком пишу в верхнем регистре.

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

 
 
 
 Re: Насколько подробно документирован Ваш внутренний код?
Сообщение18.01.2011, 08:28 
Аватара пользователя
Sanyok в сообщении #401292 писал(а):
Так что имхо, надо документировать, по-возможности - на нормальном русском языке :-)


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

 
 
 
 Re: Насколько подробно документирован Ваш внутренний код?
Сообщение18.01.2011, 09:31 
На нормальном английском не все могут. И лучше написать на нормальном русском, чем на ненормальном английском! Хотя чаще они оба ненормальные, что уж поделать.

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

 
 
 
 Re: Насколько подробно документирован Ваш внутренний код?
Сообщение18.01.2011, 10:35 
Да, мне тоже кажется, что трансилт даже с замечательного русского хуже даже плохого китайского! :mrgreen:

 
 
 
 Re: Насколько подробно документирован Ваш внутренний код?
Сообщение18.01.2011, 10:58 
Аватара пользователя
У нас обязательные: к каждому модулю, функции, параметрам функции. Остальное опционально.

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

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

 
 
 
 Re: Насколько подробно документирован Ваш внутренний код?
Сообщение18.01.2011, 11:42 
Аватара пользователя
В nginx кстати комментариев почти нет, тем не менее в его коде можно разобраться без труда (правда если привыкнуть к наименованиям).

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

 
 
 
 Re: Насколько подробно документирован Ваш внутренний код?
Сообщение18.01.2011, 13:21 
Аватара пользователя
creative в сообщении #401398 писал(а):
Может быть комментарии писать только к ключевым функциям и структурам и нетривиальным местам кода?

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

 
 
 
 Re: Насколько подробно документирован Ваш внутренний код?
Сообщение19.01.2011, 02:17 
creative в сообщении #381577 писал(а):
Очень интересно узнать насколько подробно документирован код в Вашей компании, т.е. закрытый/проприетарный код.

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

 
 
 [ Сообщений: 13 ] 


Powered by phpBB © 2000, 2002, 2005, 2007 phpBB Group