Здравствуйте, alzt, Вы писали:
A>Здравствуйте, bnk, Вы писали:
bnk>>Вещи, которые не очевидны, комментировать все еще нужно.
A>В большинстве случаев можно упростить код и сделать так, что всё станет очевидно.
Особенно очевидно смотреть на какой-нибудь интерпрайз java код, где всё на фабриках и стратегиях. А вот код который хоть что-то полезное делает надо очень поискать.
Здравствуйте, kov_serg, Вы писали:
A>>В большинстве случаев можно упростить код и сделать так, что всё станет очевидно. _>Особенно очевидно смотреть на какой-нибудь интерпрайз java код, где всё на фабриках и стратегиях. А вот код который хоть что-то полезное делает надо очень поискать.
Если фабрика добавлена ради фабрики студентом, который прочёл о паттернах, то скорее всего у кода есть куча недостатков. И фабрика там только мешает, т.к. вставлена не там, где действительно нужна. А в остальных случаях этот код проще менять и поддерживать.
Ну и в целом когда работаешь с плохим кодом, и думаешь как добавить новую функциональность так, чтобы не ухудшить его ещё. То почти всегда первым шагом будет рефакторинг: выделить интерфейсы, методы, разбить перегруженные классы, добавить фабрики и декораторы. А потом уже новая функциональность добавляется проще и гибче.
Здравствуйте, gress, Вы писали:
G>Столкнулась с новым веянием, согласно которому считается, что код комментирует себя сам. И комментарии не только не нужны, а вообще вредны.
G>Так как я боец старой формации, для меня это дикость. Но тут так получилось, что я сейчас тим лид, а мнения в команде разделились.
G>Поэтому интересно, я действительно динозавр и код теперь никто не комментирует?
Вообще, дело тут в том, что руководство всегда пытается как-то формализовать правила написания чистого, качественного, поддерживаемого кода, но задача эта нерешаема. Руководителям, да и многим рядовым разработчикам хочется иметь какие-то понятные и измеримые критерии, и часто это превращается в религию. Комментарии в коде отличный пример таких религиозных установок.
Когда-то давным давно, умные люди догадались, что в код можно вставить комментарии, в которых можно оъбъяснить для последующих поколений разработчиков, что, зачем и почему. Очевидно, что можно разъяснить все более подробно (написать побольше комментариев) и тогда код станет понятнее. Эта идея была взята на вооружение руководителями, которые стали требовать от подчиненных писать комментарии, и чем больше комментариев, тем лучше. Даже сделали всякие автоматические тулзы, чтобы подсчитать количество комментариев и настучать по голове, тому, у кого комментов мало. Что будет делать рядовой разработчик, от которого требуют написать комментарии к каждой строчке? У разработчика нет времени, его главная задача не завалить дедлайны, и ему по большей части наплевать, на тех, кто потом будет разбираться в его коде, ему просто хочется побыстрее отделаться и начать заниматься чем-то новым. Естественно он не будет долго руздумывать о том, как бы получше разъяснить неочевидные моменты, а тупо нафигачит везде очевидных и бесполезных комментов типа:
a + b // add a to b
getContext() // get context
Так шли годы, и были написаны террабайты кода с кучей бесполезных никому не нужных комментов. Потом кто-то умный высказал опять же очевидную и совершенно верную вещь: Комментарии ради комментариев не нужны, зачем комментировать очевидные вещи? А если в коде что-то неочевидное, то, может прежде чем писать комментарий, стоит подумать: не переписать ли этот кусок кода так, чтобы он и без комментариев стал понятным?
Эта идея была встречена с большим энтузиазмом, как разработчиками, которым неохота было писать комменты к каждой строчке, так и руководителями, которые надеялись, что так можно сэкономить время. И естественно это было превращено в религию! И было введено требование писать только самодокументирующийся код и не писать комментарии. Теперь, если в коде вдруг на код ревью видят комментарий, то разработчику говорят, что тут у него код написан неочевидно, и пусть он перепишет его так, чтобы комментарий был не нужен. Разработчику естественно переписывать неохота, поэтому после пары таких случаев он перестал писать комменты вообще даже там где они реально нужны, чтобы не придирались лишний раз.
То же самое касается всех остальных правил написания чистого кода, длинное имя переменной типа objectContextHandle часто несет не больше смысла чем однобуквенное. Одна длинная функция, может читаться проще чем множество мелких (не надо прыгать по коду и смотреть что делает каждая из функций). Главное не превращать эти правила в религию.
Здравствуйте, alzt, Вы писали:
A>У кода должна быть документация. Там надо описать как это собрать, что требуется установить, какая часть программы что делает. A>Как отлаживать, что означают логи. Как настроить рабочее окружение с нуля новому человеку. И куча других неочевидных вещей
Документация это те же комментарии, только вынесенные в отдельный файл. Документация тоже не компилируется и устаревает, и там точно так же может быть написана устаревшая и бесполезная информация (очень часто так оно и есть). Точно так же можно написать кучу бесполезной документации, которая будет объяснять очевидные вещи и умалчивать о том, что действительно важно.
Никакой разницы нет.
A>А в коде непонятно зачем нужны комментарии. Если комментируешь, значит код недостаточно выразителен. Лучше улучшить код, чем тратить время на комментарий.
Проблема в том, что не всегда так просто написать код который будет прост и понятен. Бывает так, что имя переменной или функции получается слишком уж длинным, что его совершенно невозможно использовать, а если имя сократить, то оно уже не совсем точно отражает, то, что делает эта функция. Бывает, что в коде для совместимости с чем-то старым надо сделать какую-то на первый взгляд совершенно ненужную вещь. Бывает, что тебе просто хочется поъянить, почему ты делаешь именно так, а не подругому, хотя на первый взгляд кажется, что должно быть не так, но это только на первый взгляд. Бывает, что где-то код приходится оптимизировать, и он получается быстрый но совершенно неочевидный.
A>А ещё комментарии не компилируются. И когда код изменится — они останутся, станет ещё хуже, т.к. вряд ли кто-то когда-то удалит этот комментарий. В любом случае на него будет тратится время.
Да, это проблема. С этим надо бороться, но точно так же фунцция может начать делать что-то новое, и ее имя перестанет отражать то, что она делает. Комментарии точно так же как и документацию надо поддерживать в актуальном состоянии. Их не должно быть много, и там надо писать именно важные вещи, а не все подряд.
A>Есть функция getUserName, и к ней написан комментарий "поменять имя текущего пользователя на новое случайно сгенерированное и вернуть предыдущее значение". Надо ли пояснять, что код плохой и комментарий не улучшает ситуацию?
Это еще не самый плохой вариант, тут сразу ясно, что либо у функции название плохое, либо коммент устарел, и надо что-то поменять.
ИМХО хуже когда так:
getUserName(); // get user name
Вот тут коммент совершенно бесполезен и не говорит вообще ни о чем. Вообще в комментарии к фунции getUserName, хорошо было бы описать возможные граничные условия и ошибки, например, что вернет функция если юзера как бы нет (он не залогинен), будет ли это null, или какое-нибудь дефолтное имя, или вообще будет exception?
A>Плохой код с комментариями лучше, чем просто плохой код. Но не на много. Лучше всё же тратить время на улучшения самого кода. А комментарии — это запашок, который подскажет, что здесь надо убрать.
Главное не давать тебе с таким подходом быть руководителем. Когда ты будешь видеть коммент, будешь сразу на них наезжать и требовать что-то переписать и убрать. В итоге они вместо улучшения кода, просто перестанут писать комменты, и вместо плохого кода с комментариями станут выдавать просто плохой код.
V>/*********************************************************
V>* File: Foo.java
V>* Purpose: Foo class implementation
V>* Notice: (c) 1066 Foo industries. All rights reserved.
V>********************************************************/
Кстати, ИМХО отличный пример бесполезной документации. Что полезного тут написано?
Что файл называется Foo.java, можно понять просто по названию файла.
Что он содержит реализацию класса Foo, ну, это и так можно понять открыв файл, и увидев, что там ничего нет кроме этого класса.
Сopyright, наверное для юристов есть какой-то смысл (хотя, для меня загадка, какой именно, если код не распространяется публично), но для разработчиков вещь бесполезная.
Javadoc вполне может сгенерировать документацию и без этого заголовка.
Польза от такой документации будет только в том случае, если там реально писать что-то полезное, но обычно народ забивает на это дело и ограничивается тупыми фразами типа "Foo class implementation" в итоге код как бы докумментирован, но смысла в этой доке никакого... фактически документации нет.
Я вообще за то, чтоб докумментировать код с помощью doxygen или javadoc, но там должно быть написано что-то важное, если это писать не охота, то лучше уж ничего не писать.
Здравствуйте, ksandro, Вы писали:
K>Документация это те же комментарии, только вынесенные в отдельный файл. Документация тоже не компилируется и устаревает, и там точно так же может быть написана устаревшая и бесполезная информация (очень часто так оно и есть). Точно так же можно написать кучу бесполезной документации, которая будет объяснять очевидные вещи и умалчивать о том, что действительно важно. K>Никакой разницы нет.
Документация компакта, и описывает высокоуровневые вещи, и то, чего просто нет в коде (например, как часто у нас релизы и почему используется именно этот стек технологий). Документацию проще писать, когда в команде появляется новый человек, либо старые переходят на другие части. То, что им не понятно — стоит добавить.
K>Проблема в том, что не всегда так просто написать код который будет прост и понятен. Бывает так, что имя переменной или функции получается слишком уж длинным, что его совершенно невозможно использовать, а если имя сократить, то оно уже не совсем точно отражает, то, что делает эта функция. Бывает, что в коде для совместимости с чем-то старым надо сделать какую-то на первый взгляд совершенно ненужную вещь.
Написать хороший код не просто, я не спорю. Добавить комментарий — это не самое плохое, но почти всегда в таких случаях можно было написать код лучше.
K>Бывает, что тебе просто хочется поъянить, почему ты делаешь именно так, а не подругому, хотя на первый взгляд кажется, что должно быть не так, но это только на первый взгляд. Бывает, что где-то код приходится оптимизировать, и он получается быстрый но совершенно неочевидный.
Если это какая-то особенность предметной области, то да. Надо добавлять подробный комментарий. Из кода это знание не получишь.
Во всех остальных случаях лучше выразить в самом коде.
K>Да, это проблема. С этим надо бороться, но точно так же фунцция может начать делать что-то новое, и ее имя перестанет отражать то, что она делает. Комментарии точно так же как и документацию надо поддерживать в актуальном состоянии. Их не должно быть много, и там надо писать именно важные вещи, а не все подряд.
Рефакторинг надо проводить постоянно. Если ты меняешь поведение функции, то надо менять и её название.
Проблемы могут только с интерфейсами возникнуть, которые связывают разные компоненты.
K>Главное не давать тебе с таким подходом быть руководителем.
Руководитель в код не смотрит.
K>Когда ты будешь видеть коммент, будешь сразу на них наезжать и требовать что-то переписать и убрать.
Комментарий показывает, что есть проблема. Его удаление проблему не решает. Но да, может сделать проблему менее заметной.
K>В итоге они вместо улучшения кода, просто перестанут писать комменты, и вместо плохого кода с комментариями станут выдавать просто плохой код.
Код ревью должно решать такие проблемы.
Нормальный подход — это не влепить коммит, который пропустят любой ценой. А написать хороший код, который будет легко поддерживать, и в котором будет поменьше багов. Если есть комментарий, то это подсказка для написавшего код — зачем он его добавил. Что он может сделать, чтобы код стал лучше без комментария.
Но без желания писать хороший код всё это бесполезно. Один ты не сможешь всех заставить писать нормално.
В среднем программисты готовы писать хороший код, если их никто не подгоняет.
Здравствуйте, ksandro, Вы писали:
K>То же самое касается всех остальных правил написания чистого кода, длинное имя переменной типа objectContextHandle часто несет не больше смысла чем однобуквенное. Одна длинная функция, может читаться проще чем множество мелких (не надо прыгать по коду и смотреть что делает каждая из функций). Главное не превращать эти правила в религию.
Ну вот нет. Много раз были длинные функции, которые вроде бы хорошо читались. Но как только разбивал их на мелкие, так всегда оказывалось, что становилось лучше.
Если вдруг длинные функции читать проще, то можно делать такой обратный рефакторинг — объединять несколько функций в одну, чтобы она стала больше. Только ни разу о таком не слышал. Подозреваю из-за того, что во-первых надо приложить усилия, а во-вторых станет хуже.
Комментируются:
1) сигнатуры методов для доксигена и проч систем автоматическойгенерации справки;
2) выборочные места в коде, которые нетривиальны с т.з. логики.
Степень "нетривиальности" определяется либо автором кода, либо максимум ревьюерами коммита.
