вопрос практикующим программистам

[mbla]

У наших студентов на пятом курсе полугодовая стажировка.

Найти стаж обычно просто - всем хочется получить готового инженера по дешёвой цене - платят стажёрам, естественно, мало.

Обычно ребят берут разработчиками на конкретные проекты.

После окончания стажировки - защита - в комиссии кто-то от нас и руководитель стажа "с места". Иногда руководитель с места по тем или иным причинам отсутствует и вместо себя присылает оценочную бумагу.

Сегодня у меня "защищал" свою работу мальчик, у которого страсть - интеллектуальные компьютерные игры. Ему удалось найти соответствующий стаж. В компании, которую 5 лет назад организовали двое братьев - совсем молодые ребята - были у них какие-то идеи, взяли кредиты. Сейчас в компании шестеро, естественно, друзья-сокурсники. Такие маленькие фирмы, по крайней мере во Франции, всегда дружеские тусовки.

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

Первое - понятное - функция должна умещаться на экране - не умещается - разбивай.

А вот второе меня поразило - комментарии запрещены. Идея в том, что комментарии позволяют писать нечётко, - дескать, прочтёт человек комментарий и всё поймёт, а на самом деле, ежели код хорошо написан, он должен быть полностью понятен при чтении с листа.

Это правило, естественно, совершенно противоречит правилам, которым учат на первом курсе, когда за отсутствие комментариев аж оценку снижают.

Как по-вашему?

Comments

[lena-shagina.livejournal.com]

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

[kot-ivanovich.livejournal.com]

Это написано в куче книжек. Самая старая, в которой мне эта мысль попадалась, была года 67-ого...

[mbla.livejournal.com]

В принципе, читать чужой код - тяжёлое дело так или иначе, в комментариях, вроде как, люди говорят, что их функция должна делать, то есть дают идею, под каким фонарём искать. Но, конечно, если функция короткая, то сильно проще.

[yucca.livejournal.com]

Я так и пишу - почти без комментариев. Но при этом ужасно мучаюсь совестью.

[mbla.livejournal.com]

Это, по-моему, наиболее частая ситуация. :-)))

[alex-legat.livejournal.com]

американские компании - заказчики софта - всегда требуют комментирования. это стандарт. чтобы другой программист смог при необходимости разобраться.

[kot-ivanovich.livejournal.com]

Хм... Я — менеджер в американской компании, которая заказывает кучу софта в России, Украине, Индии, Китае, Канаде. В гробу мы видали комментарии...

[mbla.livejournal.com]

Так вот идея этих ребят как раз в том, что другому проще разобраться в хорошо написанном неоткомментированном чужом коде, разбитом на короткие функции.

[alta-voce.livejournal.com]

Я думаю, они плохо по-французски умеют писать. ;-)
Сто лет назад комментарии поощрялись.

[mbla.livejournal.com]

Что плохо умеют писать - это точно, несмотря на то, что их учат письму в курсе communication.

[cema.livejournal.com]

Комментарии нужны, но оценку за них снижать глупо. Я пытался биться за это, но увы.

[mbla.livejournal.com]

Ну, снижают, прямо скажем, на ерунду. Что-нибудь вроде 0,5 при 20-тибальной системе.

[pendelschwanz.livejournal.com]

Так и надо.
Технология программирования которой учили в школе на заре прошлого века, строится на следующих неверных мифах:
1. Сама технолгия достаточно хороша и набрав сотню программистов с улицы из перевоспитавшихся допризывников, можно сделать большой проект.
2. Работу программиста можно измерить, и написанные спецификации увеличивают ее удельную эффективность
3. Самый большой грех - повторное написание уже написанного
4. Длиный текст не должен содержать goto потому что будет спагетти
.....................
Я знаю на самом деле только две абсолютные истины, которые очень близки к вышеперечисленной хакерской мудрости
1. Любая программа должна быть обозрима. Все что мешает обозримости (переструктурность, длинноты, комментарии) - вред
2. Программу не должен писать м$дак

[mbla.livejournal.com]

Особенно согласна с твоим пунктом 2. Это уж точно. Впрочем, и один - прекрасно. А борьба с Goto иногда приобретает религиозный характер.

Когда я программировала, я бывала неожнократно в ситуации, когда переписать было гуманнее по отношению к новоприбывшему, работающему с кодом, чем пытаться разобраться в написанном.

[liber-polly.livejournal.com]

комментарии все же нужны... может быть, не длинные, но без них очень неудобно код читать... А мне приходится.
по крайней мере, над кодом с комментариями меньше засыпаешь:))

[ivan-ghandhi.livejournal.com]

javadoc only. The rest is shit.

businesses' dilemma

[ivan-ghandhi.livejournal.com]

Гениально!

Re: businesses' dilemma

[mbla.livejournal.com]

Начинаю думать о внедрении этого где-нибудь на первом курсе, по крайней мере, требования к краткости.

[starushka-su.livejournal.com]

Хоть и не практикующий, а бывший. Самому писать комменты всегда, конечно, лениво, но читать без них ужасно хуже :)
А по поводу краткости вполне согласна

[mbla.livejournal.com]

А может, если хорошо написанный код умещается на экране, так и поймёшь? Идея в дисциплине - пиши так, чтоб код за себя говорил.

[http://users.livejournal.com/roxana_/]

Очень полезная практика получилась. Чем раньше выпускник попадает в ситуацию "а нам плевать, чему там тебя учили, у нас это надо делать вот так" - тем проще ему будет работать с самыми разными заказчиками.

[mbla.livejournal.com]

На то и стажировки!

[kot-ivanovich.livejournal.com]

Абсолютно согласен с "отцами-основателями". С функциями, не влезающими на экран, я борюсь нещадно (хотя не всегда успешно).

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

if ((x > 0) && !(x&(x-1)) {

понятно многим, но не каждому. Плохо. Переписываем:

inline bool is_power_of_2(int x)
{
return (x > 0) && ((x&(x-1)) == 0);
}
.....
if (is_power_of_2(x)) {

Теперь вроде и ежу понятно...

Исключения — отсылки к литературе или внешней документации.

Но это я именно про комментарии к коду. Комментарии к данным писать чаще надо, чем не надо...

[mbla.livejournal.com]

Убедил!!!

[andrzejn]

Совершенно правильная практика. Мы тоже её придерживаемся. Разумеется, не в формулировке "комментарии запрещены", а именно "тело метода должно быть понятно без комментариев". Для общего описания сути есть спецификации, план разбивки задания на подзадачи, комментарии в заголовке класса.

Ещё несколько правил, нагло содранных мною из идеологии Eiffel:

1. Метод должен либо изменять состояние объектов (процедура), либо возвращать значение (функция). У функций побочных эффектов быть не должно. Помогает избегать глюков типа "вставили функцию в проверку условия и забыли о побочных эффектах" и искать вредные побочные эффекты (в функции можно не заглядывать).

2. Перехватчик исключений (блок try...catch/finally) должен быть один на метод, чаще всего - охватывать всё тело метода. Если нужно больше - надо дробить метод на несколько. Это требование того же рода, что и "функция должна помещаться на экране". Метод должен делать только одно логическое действие, а не сначала одно, потом другое.

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

[mbla.livejournal.com]

Понятно. Про побочные эффекты - это борьба с программистами на С, которые обожают строить решения на побочных эффектах.

[clement.livejournal.com]

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

[andrzejn]

Мне больше нравится идея, что эти условия и инварианты лучше оформлять в виде assert'ов, чтобы не только программисты их читали, но и при исполнении их нарушение контролировалось. В комментарии выносить разве что те условия, которые проверяются недопустимо долго.

[a_p]

Такая практика может быть полезна для обучения программированию, как и вообще следование каким-то допускающим обоснование правилам (типа функция не больше 30 строк). С опытом (или просто с возрастом? :)) фанатизм в следовании правилам проходит. То есть комментарии используются там, где надо, а функции, хоть и редко, вылезают за экран.

Вообще, следование общим правилам восполняют недостаток конкретного умения-понимания. Поэтому оно полезно в неоднородных по уровню коллективах.

[mbla.livejournal.com]

Ну, про следование общим правилам при недостатке конкретного понимания - это, пожалуй, не только к программированию относится.

[afrolover.livejournal.com]

Да кому они вообще нужны, эти комментарии? Особенно, когда вы пишете функцию типа "возведение в степеь целого числа".

А в реальной жизни иногда подолгу думаешь, как оптимизировать тот или иной кусок кода. Так вот, тот, кто будет читать этот код (без комментариев) проведёт ещё больше времени, чтобы его понять...
Я уж не говорю, что есть вещи, которые просто нечитабельны. В C++ шаблоны (templates) нечитабельны. Будьте вы плохим программистом или хорошим. Это не от вас зависит - это проблема языка. Поэтому комменты, пусть самые кратенькие, очень скрашивают жизнь...
Ща попробую выковырять откуда-ниб примерчик

// [if O1_size available, then attempt which_t size optimization...]
// [select signed char if fewer than SCHAR_MAX types, else signed int:]
typedef typename mpl::apply_if<
mpl::equal_to< mpl::O1_size, mpl::long_<-1> >
, mpl::identity< int >
, mpl::if_<
mpl::less< mpl::O1_size, mpl::int_ >
, signed char
, int
>
>::type which_t;

на мой взгляд, комментарии тут совсем не лишние...

[greenadine.livejournal.com]

Или взять perl. Кусочек кода без комментариев...

[greenadine.livejournal.com]

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

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

Но, естественно, гораздо чаще встречаются i = i + 1; // uvelichivaem i na edinicu.
К слову, не рекомендовал тебе еще сайт с говорящим названием (http://www.thedailywtf.com/) (у него есть трансляция в ЖЖ - daily_wtf), в котором собираются the worst practice. Не знаю, как преподавателю, но мне довольно интересно смотреть, чтобы на те же грабли не наступить, или просто повеселиться. Вот примерчик (http://www.thedailywtf.com/forums/43457/ShowPost.aspx) с изумительными комментариями.

[mbla.livejournal.com]

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

разве качество продукта и комментарии противоречат др

[eutrapelia.livejournal.com]

На самом деле существуют некоторые требования к готовому продукту, эти требования включают достаточно подробное комментирование. С другой стороны, при, к примеру, инспекции кода на этапе тестирования, требуется, чтобы код проверялся людьми сторонними, без объяснений, тогда требованием к коду становится его доступность без объяснений. Комментарии зачастую добавляются на завершающем этапе разработки.
Так что мальчики просто максималисты, а соблюдение и того, и того правила повысит качество продукта.

Re: разве качество продукта и комментарии противоречат

[mbla.livejournal.com]

Я думаю. что цель у них двойная - с одной стороны, чтоб писали понятно, а с другой, - чтоб не было совершенно идиотских бессмысленных комментариев. Вообще говоря, распростанённый способ поведения - сначала написать код, а потом поставить комментарии не там, где нужно, а там, где попроще их навалять.

[ksl-aka-serg.livejournal.com]

Все комменты не читал, т.к. мало времени, но бегло пробежавшись, увидел, что большинство тебе ответивших против комментариев.
Выскажу и я свое мнение. Я - программист с 25-ти летним стажем. Любые формальные правила в нашем деле вредны. (Я против использования goto, но иногда его неприменение сильно ухудшает прозрачность кода.) Что касается длины функций, то да, чем короче, тем понятней, но опять же, возможны случаи, когда прозрачность при разбиении потеряется. Тогда данное правило вредно. Попробуй напиши функцию пирамидальной сортировки в один экран!

Что касается комментариев, то это полный бред. Не писать комментарии можно только в том случае, если команда очень маленькая - полукустарная, во-первых, во-вторых, абсолютно отсутствует текучка, в-третьих, жизненный цикл данного программного обеспечения сильно ограничен по времени. Ну, кого через пять лет будет интересовать код давно устаревшей игрушки?
Если же мы говорим о промышленном программировании, то комментарии необходимы.
Во-первых, если говорить о таком языке как С++, то он не очень прозрачен. Даже при очень высокой квалификации программиста, не все конструкции доступны для легкого понимания. Например, шаблоны.
Промышленное программирование подразумевает, что код должен быть сопровождаемым и легко модифицируемым. Т.е. пройдет несколько лет, и возможно, читать этот код придется другому человеку, и не факт, что код тот писал очень прозрачно пишущий программист.
В том программном продукте который мы сейчас выпускаем имеется некий engin, написанный мной со товарищи в количестве 5-ти человек аж в 91-м году. Из той команды остался только я один. Изредка возникает потребность в модификации кода. Комментарии даже в тех кусках, которые я писал сам, сильно убыстряют вспоминание.
Еще про сопровождение. В 87-м году мне вручили на сопровождение код, который писала женщина, уходящая в декрет. Во тогда-то я понял о чем думает беременная женщина. :-) О чем угодно, но только не о структуре программы. Нанайский стиль программирования: о чем думаю, то и кодирую. Слава богу, она была дисциплинированной девочкой, и оставила довольно много комментариев.
Т.е. не всегда мы имеем дело с кодом, написанным супер-программистом, пишущим прозрачно. Ладно, девочка та была несчастным случаем. В середине 90-х я нанял на работу бывшего доцента с кафедры высшей математики Бауманки. Гениальный человек! Необыкновенная продуктивность! Эффективнейший код! (Тогда компьютеры были существенно медленнее, а задачи-то у нас реального времени.) Но код, боже! Какой он писал непрозрачный код! Пришлось пригрозить увольнением, что надо писать комментарии.

Мастер Йода, точнее Йодан, в своей книге про искусство структурного программирования писал, что оптимальное соотношение кода к комментам должно быть 5:1. Йоду еще никто не отменял, и те принципы, которые он сформулировал, живы до сих пор.

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

[ksl-aka-serg.livejournal.com]

Йода, конечно же пербарщивает. Сейчас такое колличество комментов не нужно.