Этично ли включать комментарии к коду, основанные на мнении, для будущих разработчиков?

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

Вопросы: этично/профессионально ли оставлять комментарии к соответствующему кодексу, объясняющие ваши мысли/рассуждения, которые могут частично основываться на личном мнении? Если бы вы были работодателем и обнаружили, что один из ваших предыдущих сотрудников сделал это, что бы вы подумали? Как еще можно разрешить эту ситуацию?

Пример: Тип комментария, который вы бы включили, будет примерно таким:

Примечание разработчика: этот процесс был задуман как «проверка концепции» вопреки моему здравому смыслу и может быть нарушен. Есть некоторые известные ошибки, и этот процесс может быть сложно поддерживать. Извините, если вам нужно сохранить это, это был единственный доступный вариант в то время.

ИЛИ ЖЕ:

Примечание разработчика. Этот процесс может прерваться при увеличении объемов данных. Было бы предпочтительнее использовать массовый экспорт, однако в то время это было невозможно. Существует настройка журнала ошибок, чтобы предупредить, если этот процесс выполняется слишком долго и его можно найти в месте X.

Комментарии не для расширенного обсуждения; этот разговор был перемещен в чат .
Комментарии внутри самого кода должны быть как можно короче и относиться только к следующему за ним коду. Все остальное (более длинные пояснения, бизнес-процессы, причины делать что-то определенным образом) должно быть помещено в отдельную документацию для проекта/приложения.
@MonicaCellio -- Re «Комментарии не предназначены для расширенного обсуждения; этот разговор был перемещен в чат». В этом комментарии относительно комментариев в коде есть восхитительная ирония. Комментарии в коде также не предназначены для расширенного обсуждения.

Ответы (19)

Я бы назвал это не этичным/неэтичным, а профессиональным/непрофессиональным.

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

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

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

Сделайте комментарии доступными для обнаружения, используя известные префиксы «XXX» или «FIXME» . Это то, на что должен обратить внимание новый разработчик, когда ему нужно копаться в кодовой базе, а также то, что IDE обычно выделяют, собирают и показывают в обзоре.
просто фраза «вопреки моему здравому смыслу» безумна и нелепа. все остальное совершенно нормально и ничем не примечательно.
Соглашаться. Я думаю, что предупреждение о том, что он, как ожидается, сломается, требует документации, но весь тон «эй, я не хотел этого делать, не совсем моя вина» в первом — это личное выражение. Второй кажется гораздо более «просто фактами» и профессиональным.
@JonasWielicki TODO: еще один довольно популярный вопрос, который автоматически ищет большинство инструментов.
@JonasWielicki Я использую TODO, хотя я также видел FIXME и DEBUG. Является ли XXX фактическим кодом или это означает другие слова, такие как TODO и FIXME?
@ Anon234_4521 Anon234_4521 По крайней мере, в Java фактически используется XXX , и он поставляется, например, с настройками Eclipse по умолчанию. Более того, он включен в соглашения Oracle/Sun. Похоже, что он используется и в других местах, и является своего рода «проваленным» комментарием, где FIXME и TODO слишком специфичны.
@ Anon234_4521 XXXв значительной степени означает то, что вы можете себе представить: «этот бит облажался!» (т.е. хакерский / экспериментальный / неоптимизированный / способный взломать код). Он используется для пометки кода, который действительно работает , но разработчик действительно должен знать лучше, и его следует улучшить в соответствии с любым достойным профессиональным стандартом, когда пыль уляжется и у кого-то появится здравый смысл сделать код более удобным для сопровождения. Т.е. именно ту ситуацию, которую описывает ОП. (В отличие от FIXMEкода, который по определению сломан и поэтому нуждается в исправлении, или TODOкоторый еще не реализован).
Или вместо этого сообщите об ошибке в вашей системе отслеживания проблем.

Будьте конструктивны.

Комментируйте такие вещи, как ошибки и проблемы, поскольку они помогают как проекту, так и новому разработчику, но держитесь подальше от комментариев типа «Извините, если вам нужно это сохранить», в них мало смысла.

Первый читается немного непрофессионально, ИМО, и осмелюсь сказать, что он немного раздражителен со ссылками на «вопреки моему здравому смыслу». Если бы я видел это как менеджер разработчика, я бы не смотрел на это слишком любезно.

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

+1, и я думаю, что это можно было бы улучшить, указав это как документацию, рассказывающую будущим сопровождающим о предположениях. Например, "этот код предназначен только для объемов менее X .... в секунду. Более высокие объемы могут привести к нестабильности" Только факты, мэм.
Я думаю, что часть «вопреки моему здравому смыслу» в порядке. Это говорит о качестве кода, который вы можете ожидать найти. «Если бы я видел это как менеджер разработчика, я бы не смотрел на это слишком любезно». -> Это заставляет вас звучать мелочно и/или некомпетентно. Если вы как менеджер принимаете плохое техническое решение, вы должны признать это.
@industry7 Мне всегда принадлежали технические решения, которые я принимал как менеджер, хорошие и плохие. Мои отчеты не всегда согласовывались с ними, и это нормально, и я призываю их высказывать свое мнение. Пассивно-агрессивное снайперство с помощью комментариев к коду — не лучший способ показать это.
@motosubatsu «Я призываю их высказывать свое мнение. Пассивно-агрессивные замечания с помощью комментариев к коду — не лучший способ показать это». Комментарии к коду предназначены не для вас, менеджера, они для других программистов, которые могут не знаю, что вы, менеджер, вынудили разработчиков принять плохое техническое решение. И разработчикам действительно полезно в будущем знать, ПОЧЕМУ было принято конкретное техническое решение, и если единственная причина — «так сказало руководство», то действительно полезно иметь эту информацию в комментариях к коду.
@industry7 Я не думаю, что мы встретимся во взглядах на этот вопрос, возможно, потому, что во время моей работы менеджером я всегда был технически «практическим», поэтому комментарии к коду очень важны для меня.

Этично/профессионально ли оставлять комментарии к соответствующему кодексу?

Профессионально и обязательно: тем, кто работает над этим, потребуются комментарии, чтобы сэкономить время / деньги / головные боли.

объясняя свои мысли/рассуждения, которые могут быть частично основаны на мнении?

Избегайте этого. Придерживайтесь фактов. Сохраняйте профессиональный подход и будьте конструктивны, как отметил @ Seer.The.

Прокомментируйте техническую часть ошибки, объясните, если нужно, используйте TODO-список, порекомендуйте что-нибудь полезное, если это профессионально и связано с вашей работой/кодом.

Примечание разработчика. Этот процесс может прерваться при увеличении объемов данных. Журнал ошибок можно найти [ ЗДЕСЬ ], чтобы предупредить, если процесс выполняется слишком долго. В будущем может быть полезно ("Планировалось" / "может быть полезно"): а) проверить ААА б) изменить ВВВ в) протестировать ССС

Ни один менеджер или босс не хотел бы видеть неконструктивную, основанную на мнении критику.

  • Не

    • скажи, что это неправильно
    • скулить
    • жаловаться
    • писать нетехнические комментарии, основанные на мнениях (*)

  • Предпочитаю :

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

/* (*) РЕДАКТИРОВАТЬ : 2017-06-30: добавлено «нетехническое» в « Не перечислять», чтобы сделать его более понятным, на основе Wildcardкомментария @. */

Я мог бы добавить Не: «Извиняйтесь (это бесполезно, и следующий человек не узнает вас и не обидится; это просто занимает место)»
Технические заключения в порядке. «Нам, вероятно, не нужно беспокоиться о поддержке версий API foobar до 2.0; или, по крайней мере, это слишком много работы для этой итерации». По крайней мере, дает контекст, почему они не поддерживаются.
Соглашаться. Я думал о комментариях, основанных на мнениях, так, как их упомянул ОП. Но профессиональные комментарии, основанные на техническом мнении, очень приветствуются.
Не помещайте todos в код; поместите их в свою систему отслеживания проблем.

Когда я когда-либо оказывался в ситуации, когда мне приходилось что-то брать, а не оставаться наедине с документами и комментариями о производственном коде, и мне не с кем было связаться,

Мне бы очень хотелось найти подсказки, основанные на мнениях. Но все, что я обычно нахожу, это:

//TODO!!!!

Поэтому я бы сказал, задокументируйте это настолько технически и точно, насколько сможете, но прежде чем опустить важную информацию , ваша замена простит вас за то, что вы основываетесь на мнении, а не просто пишете еще один комментарий «Я не закончил это» /*TODO!!!!*/.

Ну, по крайней мере, я бы.

Todo: Напишите конструктивный комментарий к этому ответу.
@Wildcard: тогда вам следует добавить этот вопрос в избранное, чтобы не забыть о нем. Вот откуда берется мой постоянно увеличивающийся список любимых ОП ;P
Стандарт TODO:принят множеством инструментов и разработчиков.
... но было бы лучше сделать запись в вашей системе отслеживания проблем.
@LightnessRacesinOrbit: Справедливое замечание, но шутки в сторону: не каждая компания приложила усилия для поддержки такой системы, хотя я думаю, что нет ни одной компании, которая еще не поддерживала бы какие-либо комментарии.

Поскольку вы спрашиваете: «Как еще можно справиться с этой ситуацией?», я собираюсь немного выйти за рамки и сказать:

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

Серьезно. Если вы считаете, что в вашем коде есть ошибки, вы пишете отчет об ошибке. Вы используете любую из множества систем отслеживания проблем (например, Bugzilla), которые находятся в свободном доступе и просты в использовании и обслуживании. Черт, используйте электронную таблицу Excel, если хотите. Отчеты об ошибках могут быть настолько подробными или предположительными, насколько вам нравится. Они могут (и должны!) содержать обоснования того, почему руководство могло принять решение не исправлять их. Это все лучшие практики для разработки программного обеспечения.

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

Если я обнаружу, что нет трекера ошибок, я буду беспокоиться. Хуже того, если я обнаружу, что код изобилует комментариями о том, что «это может сломаться», я прокляну ваше имя. Единственный способ найти возможные ошибки в системе — просмотреть каждый файл, строка за строкой, потому что я понятия не имею, какие еще мины вы оставили для тех, кто занимается сопровождением.

Так что работайте правильно. Размещайте свои отчеты об ошибках в системе отслеживания ошибок. Сделайте их максимально подробными. Включите имена менеджеров, которые приняли решение не исправлять ошибки — это будет жизненно важной информацией для будущего сопровождающего, чтобы найти нужного человека, с которым можно поговорить. Если вы хотите добавить в свой код комментарии, говорящие: «У этого есть известная проблема — подробности см. в CR1234», то вы делаете все возможное.

Но на самом деле не рассматривайте комментарии к коду как подходящее средство сообщения об ошибках для сопровождающих. Это не так.

Этот. Именно это. Это код; будут баги . Вопрос не в том, существует ли хрупкий код, а в том, задокументирован ли хрупкий код — // HERE BE DRAGONSкомментарий — это не документация . Я бы только добавил, что журналы изменений и отслеживание проблем просто не относятся к комментариям к коду . Они относятся к системе управления версиями и системе отслеживания проблем соответственно.
Это не совсем то, о чем спрашивает плакат. Существование метода отслеживания ошибок не означает, что код нельзя комментировать, и если в настоящее время нет воспроизводимой ошибки, как вы поместите ее в отчет об ошибке? Примечания к выпуску, возможно...
@barbecue ОП ясно дал понять, что думает, что это сломается . Отчеты об ошибках абсолютно действительны для всего, что ведет себя неправильно или может вести себя неправильно, независимо от того, есть ли у вас хорошие средства для их воспроизведения. И проблемы могут быть подняты для всего, что потребует решения, независимо от того, является ли это ошибкой или нет. Я согласен (и сказал в своем ответе), что вы можете добавлять комментарии , а также создавать отчет об ошибках / проблемах; но ОП рассматривал комментарии как единственный способ документирования проблем, и это следует считать вредным.
@ Грэм «он, ОП, рассматривал комментарии как единственный способ документирования проблем». Где вы видите это в вопросе? Я не вижу ничего подобного. Вопрос был конкретно о том, можно ли размещать в коде комментарии, описывающие уязвимость, которую разработчику запрещено исправлять. В нем вообще не упоминается отслеживание ошибок или другие формы документации, а указание ему поместить проблему в систему отслеживания ошибок не решает вопроса о том, этично ли добавлять комментарии к коду о политических/неполитических проблемах. - принятое техническое решение.
@barbecue Он конкретно спрашивает: «А как еще с этим можно справиться?» Поскольку это его вопрос, он не рассматривал его каким-либо образом, кроме комментариев. Что касается этики, дублировать информацию не рекомендуется, поэтому, если он уже поднимал проблему, он никогда не должен дублировать эту информацию в комментариях. Какой контент он помещает в комментарий, не имеет значения — если он поместит его в комментарий, он автоматически потерпит неудачу. Что касается того, что происходит в проблеме, личное мнение допустимо, если оно конструктивно и проблема точно описывает, что идет не так.
«поместив это в комментарий, он автоматически провалился». Широкие обобщения всегда ошибочны. Никто "автоматически" не терпит неудачу, потому что они помещают комментарии в код, это просто глупо.
Обычно я бы согласился, но это не ситуация с ошибкой; это скорее «Это код на 100% соответствует спецификации, но у меня есть оговорки по поводу самой спецификации». Если рассматривать это как ошибку, это будет давать все неверные сигналы и, возможно, даже причинить вред (например, путем внесения новых ошибок или задержек, когда программное обеспечение «просто работало» в глазах руководства). Это проблема, которая только и ждет своего возникновения, но, к сожалению, еще не возникла, чтобы оправдать вмешательство. За исключением формального отчета (который вряд ли будет прочитан), я думаю, что комментарии «мнения» прямо там, где это важно в коде, действительно являются подходом.
О боже, да это. Бесполезно засорять код расплывчатыми фразами «это могло бы быть лучше». Поднимите ошибку, документируя конкретную проблему. Тогда с этим можно справиться, как и с любым другим вопросом качества, т.е. должным образом .
@barbecue: «если в настоящее время нет воспроизводимой ошибки, как вы поместите ее в отчет об ошибке?» Вы можете создать отчет об ошибке качества кода или хрупкой инфраструктуры без воспроизводимой ошибки. Если вы еще этого не сделали, возможно, что-то не так с вашими процессами.
@LightnessRacesinOrbit Ради Бога, пожалуйста, примите мое заявление в контексте и не делайте глупых предположений о моих собственных процессах.
@barbecue: я не делал никаких «предположений»; Я сказал, что может быть что-то не так. Не нужно злиться.
@barbecue «Никто «автоматически» не терпит неудачу, потому что они помещают комментарии в код, это просто глупо». Конечно нет, потому что это не то, что я сказал, и очень глупо поднимать эту чучело, чтобы предположить, что я это сделал. Я сказал, что если вы используете комментарии в коде, чтобы уведомить сопровождающих об ошибках , вместо того , чтобы поднимать ошибку как отчет об ошибке в системе отслеживания ошибок, то вы автоматически терпите неудачу. Это «широкое обобщение», сделанное стандартами разработки программного обеспечения и десятилетиями передового опыта в отрасли, а не только мое личное мнение.
@TasosPapastylianou Как человек, который работал над программным обеспечением, связанным с безопасностью и с высокой степенью критичности, я искренне заинтригован, почему вы считаете, что вмешательство оправдано только после сбоя программного обеспечения? Что касается «сигналов», руководство может принимать решения только в том случае, если вы предоставляете им достоверную информацию. Если вы скажете им, что «это может пойти не так, но это практически невозможно сделать», то они могут соответствующим образом снизить приоритет. Если вы скажете им, что «в этом коде нет ошибок», они даже не узнают об этом. А активное сокрытие потенциальных проблем от руководства называется грубой халатностью или должностным преступлением.
@ Грэм, ну, я так не думаю и не предлагал, и я полностью согласен со всем, что вы сказали. Я имел в виду другое. Похоже, что информация по этому вопросу была предоставлена ​​и адекватно обсуждена с руководством, и они приняли решение не обращать на нее внимания, несмотря на протесты ведущих разработчиков. В этом случае лучший (хотя и не обязательно «хороший») план действий ведущего разработчика — просто упомянуть информацию, которая будет полезна будущему сопровождающему , если что-то пойдет не так (будь то в коде или в отчете об уходе). Но (продолжение)
сообщение об ошибке или проблеме, которая, по сути, гласит (вежливо или как-то иначе): «на самом деле там нечего исправлять, просто оставьте эту проблему задерживаться и засорять наш трекер проблем до тех пор, пока эта проблема не возникнет из-за плохих решений руководства, с которыми я не согласен». " не очень хорошее применение для трекера. Если это не проблема, которая будет рассмотрена, и она предназначена только для того, чтобы служить чьим-то разочарованным (хотя и полезным) предостерегающим разглагольствованием, я считаю, что вместо этого лучше оставить комментарий. В лучшем случае может быть заметка на будущее для переоценки, но она также не относится к системе отслеживания проблем.
@TasosPapastylianou Извините, если неправильно истолковал ваш комментарий. Полностью согласен, разглагольствование никому не нужно. Но система отслеживания ошибок должна иметь категорию/приоритет для «потенциально может произойти, но исправление отложено на неопределенный срок, пока/если у нас не будет доказательств того, что это действительно проблема для кого-то». Может быть, никто и никогда ничего не сделает с десятками жуков, лежащих в дремлющем состоянии в этой категории, но вы не знаете заранее, какой из этих десятков жуков вдруг оживет. И тогда ценность любой имеющейся у вас информации, какой бы отрывочной она ни была, выше золота.
@TasosPapastylianou ... Первая задача с новым отчетом об ошибке - проверить, сообщалось ли об этом уже (поиск дубликатов и регрессий), и средство отслеживания проблем - это то место, куда вы идете, чтобы проверить это. Дело не в том, что нечего исправлять, а в том, что руководство не думает, что исправление добавляет ценности. Это не обязательно должно быть разглагольствование, но в проблеме, безусловно, может быть записано, кто это решил, и это более полезная информация для сопровождающего.
Ужасные коммуникативные навыки проявляются в этих комментариях.
@Graham Вот ТОЧНАЯ цитата из ваших слов: «Содержимое, которое он помещает в комментарий, не имеет значения - помещая его в комментарий, он автоматически терпит неудачу». Вы прямо заявили, что содержание комментария не имеет значения, сам факт размещения комментария является провалом. Теперь вы можете утверждать, что это не то, что означают эти слова, но это просто неверно. Вы ДЕЙСТВИТЕЛЬНО заявили, что размещение ЛЮБОГО комментария, независимо от его содержания, является автоматическим отказом. Если это не совсем то, что вы имели в виду, то вам следует перефразировать, потому что это И ЕСТЬ то, что вы сказали.
@barbecue Пожалуйста, перестаньте строить больше соломенных чучел, цитируя вне контекста, потому что вы просто выставляете себя еще более глупым. Но так как вы явно новичок, объясню построчно. «Поскольку это его вопрос, он не рассматривал его каким-либо образом, кроме комментариев». Отчеты об ошибках принадлежат баг-трекерам. Если вы просто добавляете комментарий, вы потерпели неудачу в соответствии с любой передовой практикой разработки программного обеспечения, на которую вы хотели бы взглянуть.
@barbecue Но давайте предположим, что он помещает одну и ту же информацию в систему отслеживания ошибок и в комментарий. «Что касается этики, то дублировать информацию не рекомендуется, поэтому, если он уже поднял проблему, он никогда не должен дублировать эту информацию в комментариях». Так что, если он сделал это, то он также потерпел неудачу по другой причине.
@barbecue «Контент, который он добавляет в комментарий, не имеет значения — если он поместит его в комментарий, он автоматически потерпит неудачу». Таким образом, использует ли он комментарий в качестве основного хранилища для записи об ошибке или дублирует информацию между системой отслеживания ошибок и комментарием, оба этих варианта терпят неудачу.
@barbecue Обратите внимание, я ни разу не сказал, что он потерпел неудачу, потому что он добавил комментарии в код. Я сказал, что он потерпел неудачу, потому что использовал комментарии для записи подробностей об ошибках . Как я объяснял в своих рассуждениях, как бы много или как бы мало информации он ни поместил в комментарий об ошибке , эта информация всегда относится к системе отслеживания ошибок, а не к коду.
@ Грэм, опять же, как я уже указывал, возможно, это было то, что вы имели в виду, но фактические слова, которые вы использовали, не означают этого.

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

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

Что часто гораздо полезнее, чем информация о том, почему что-то было сделано определенным образом, так это информация о том, почему что-то не было сделано определенным образом, особенно если этот другой способ может «показаться» лучше. Комментарий «Может показаться, что быстрее сделать X вместо Y, но это приведет к неразрешимой проблеме Z» иногда может принести большие дивиденды, если спасет многих других от попыток реализовать «улучшенную» версию кода, которая делает Y вместо Y. X, тратя еще больше усилий на то, чтобы исправить это, и, наконец, приходится откатываться, чтобы снова сделать X.
Ага, но комментарий типа "руководство заставило меня так поступить. Извините, что вам приходится с этим разбираться" мало кому полезен.
@Casey, напротив, это может быть очень полезно, но формулировка должна быть значительно улучшена, если это действительно так. Пример: «Если вам интересно, почему подход X не использовался и был ли он лучше, скорее всего, да, но текущее руководство определило, что в этот проект уже вложено достаточно ресурсов. Если вы просматриваете этот код, чтобы улучшить его производительность и надежность, подход X кажется мне наиболее вероятным кандидатом».

Много лет назад мне пришлось внести некоторые изменения в программу, написанную кем-то другим, и я наткнулся на большой блок комментариев в середине кода, который начинался словами: «Это печальный комментарий о современной Америке, когда человек вынужден продолжать работать». над проектом, который ему не интересен», и продолжал и говорил о том, как этот человек ненавидит свою работу. Затем он закончил комментарий и вернулся к перетасовке данных. Я упомянул об этом одному из других программистов, и она сказала, что этот парень всегда вставлял эти разглагольствования в свой код. Это было довольно забавно, но выглядело довольно глупо.

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

Я обычно включаю в код комментарии, описывающие ограничения. «Эта функция медленная, но она вызывается не очень часто, поэтому это не имеет особого значения», «Эта проверка работает только для адресов в США — ее придется изменить, если мы когда-либо будем обрабатывать иностранные адреса» и т. д.

В общем, я считаю правильным и разумным писать комментарии, в которых прямо говорится: «вот ограничения того, как мы это сделали, но мы пошли на этот подход, потому что…» Будущий программист тогда имеет представление и не имеет чтобы заново во всем разобраться. Я уверен, что любой, кто был в бизнесе достаточно долго, бывали времена, когда он говорил: «Вау, это было сделано очень плохо, я собираюсь переписать это таким образом», а затем мы тратим часы (или месяцев) на переписывание, только в какой-то момент обнаружил: «О, это не работает. Теперь я знаю, почему первоначальный программист сделал это именно так».

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

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

Однажды мне пришлось написать код, который включал принудительное использование пробелов с помощью множества   вместо использования CSS (не по моему собственному выбору). Я оставил комментарий «играй в глупые игры, выигрывай глупые призы» выше всех  s.

Я в той же лодке - может быть, у меня чуть меньше времени до отъезда, чем у вас.

Решение, согласованное в нашем случае (я думаю, хорошее), было:

  • Выполняйте свою задачу профессионально, когда это возможно (в вашем примере выберите второй вариант).
  • В рамках передачи подготовьте документ с наиболее вероятными/ожидаемыми источниками проблем/проблем.
  • В этом документе вы можете изложить текущие проблемы в архитектуре программного обеспечения, высказать свое мнение и даже предложить возможные способы их решения.

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

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

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

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

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

Вы говорите: «Но вы становитесь обузой для компании, если публикуете эту информацию, потому что вы сводите на нет любые будущие претензии правдоподобного отрицания», как будто это плохо, как будто вы хотите помочь компании скрыть юридически сомнительную деятельность.
@ Аарон, я не не согласен с тобой, но это то, что есть. Ни один работодатель не будет держать рядом с собой человека, чья профессиональная неосмотрительность подвергает его юридическому риску.
@Aaron: Вы можете стать жертвой легкомысленного судебного процесса, быть абсолютно невиновным, а из-за какого-то глупого комментария вы проиграете дело в суде.
@Johnny написал: «Ни один работодатель не будет удерживать ...» Мой работодатель обеспечивает строгую политику и инструкции, сопровождаемые обучением, о том, как сообщать обо всех юридических проблемах, и предоставляет нам номера телефонов государственных учреждений, к которым можно обратиться напрямую. Я полагаю, что это необычно, хотя. В моем случае, я в настоящее время работаю в огромной многомиллиардной компании в бизнесе, где неудачные судебные тяжбы могут стоить сотни миллионов, поэтому они хотят иметь возможность сказать: «Мы сделали все возможное, чтобы полностью соблюдать закон. ... Мы больше ничего не могли сделать». Меня бы уволили за правдоподобное отрицание.
@Aaron Мы, вероятно, работаем в одной отрасли. То, что вы описываете , это отрицание. Ни от кого из нас не ожидается, что мы устраним риск — любой бизнес имеет неотъемлемый риск — но мы должны свести его к минимуму как агенты, действующие от имени наших работодателей. (Кроме того, я не говорю здесь о сокрытии нацистского золота или отмывании денег, а просто о развертывании потенциально проблемного программного обеспечения и о том, что компания берет на себя такой риск на рынке, в судах и в сфере PR. Это не является незаконным. Это не распространяется на них. принимая на себя риск того, что их агенты развернут его со встроенными признаниями злоупотребления служебным положением.)
@Johnny написал «развертывание со встроенным признанием злоупотребления служебным положением». Я с тобой согласен. Возможно, тогда мы обсуждаем яблоки и апельсины. Случаи, о которых я думал, и случай, который вы описываете, должны иметь разные реакции/результаты. Я полагаю, что это должно оцениваться в каждом конкретном случае. Хотя, подумав об этом еще раз на этой неделе, я соглашусь, что если что-то не следует скрывать и вам нужно защитить себя, комментарии в коде — не место для защиты ваших действий. Если вам нужна юридическая защита, другие возможности были бы лучше. +1 к вашему ответу.

Сам как программист...

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

Существует строгое ограничение на объем обрабатываемых здесь данных, так как мы перебираем всю базу данных и извлекаем каждую строку. Буферы отката уже установлены администраторами на DB1 и DB2 настолько большими, насколько это возможно, но при типичном трафике (по состоянию на июнь 2017 г.), который дает нам только 2 часа времени в самый спокойный период между 03:00 и 05:00, и (по состоянию на июнь 2017 г.) пробежка занимает 1:40 (+/- 3 минуты).

Сравнительный анализ показывает, что это ограничение программного и аппаратного обеспечения БД для чтения и отправки данных, а параллельная обработка и секционирование уже применяются, насколько это возможно, без риска несогласованности данных.

Из-за бизнес-логики, ограничений продукта и аппаратного обеспечения, особенно A, B и C, невозможно использовать временные таблицы, эти и D и E также не позволяют нам просто выгружать или массово экспортировать базу данных. Другим рассмотренным вариантом была репликация БД на DB_r, отключение репликации DB_r и работа над этим. К сожалению, возврат к актуальной репликации создает слишком большую нагрузку на DB1 и DB2, и это становится еще хуже с постоянно растущим объемом данных.

На адрес development@company и admin@company отправляется автоматическое электронное письмо (с указателем на эту часть кода), если время выполнения превышает 1:45, а другое — для 1:55; он также будет зарегистрирован системным журналом как серьезный / критический. (Адреса электронной почты задаются в /blah/blubb/const.h, вы можете добавить свою электронную почту, если по какой-то причине вас нет в списке.)

Руководство было проинформировано, что в ближайшем будущем это станет проблемой, но им может понадобиться напоминание о том, что ближайшее будущее превратилось в настоящее. Возможные решения:

  • Измените RAID БД с жестких дисков на твердотельные накопители и получите больше оперативной памяти и больше ядер для серверов БД --- быстро, но дорого (также лицензии на программное обеспечение БД)
  • Переключитесь на XXX DB или YYY DB, что позволяет разумно экспортировать из работающей БД, но не имеет функциональности X и Z, так что код необходимо адаптировать к этому --- что будет стоить серьезных денег на программное обеспечение и время изменить и проверить код
  • Перемещение старых данных в «архивную» или «хранилище данных» БД уменьшит объем данных в DB1 и DB2 как минимум на 50%, может быть, на 80%, что решит или, по крайней мере, отсрочит проблему на несколько лет. - Продажи должны быть убеждены в том, что обработка их статистики на основе данных менее чем за один день действительно жизнеспособна, что исторически было сложно. Также это означает, что необходимо новое оборудование.

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

Тесты, по-видимому, показывают, что если вы реплицируете БД в DB_r, а затем в DB_r_r, вы можете поддерживать низкую нагрузку из-за репликации DB1 и DB2, когда вы передаете эту работу в DB_r, но из-за отсутствия достаточного количества оборудования это не может быть протестировано с реалистичным объемы данных.

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

Подобная заметка так There are some known bugsже полезна, как «Остерегайтесь снаргелов!» И поскольку следующим человеком, который будет поддерживать этот код, будет психопат с штукой для бензопилы, который знает ваш текущий адрес...

Однако этот длинный блок контента, вероятно, не должен находиться в комментариях к коду. dev-notesИМО было бы лучше добавить папку в систему управления версиями и поместить ее туда со ссылкой на этот файл, включенный в комментарии к коду.

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

Примечание разработчика. Этот процесс может прерваться при увеличении объемов данных. Было бы предпочтительнее использовать массовый экспорт, однако в то время это было невозможно. Существует настройка журнала ошибок, чтобы предупредить, если этот процесс выполняется слишком долго и его можно найти в месте X.

Скорее, вы могли бы пойти с чем-то вроде:

Этот алгоритм следует изменить на массовый импорт, если объем увеличивается до X записей/выполнение занимает более часа.

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

Если сомневаетесь, комментируйте больше.

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

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

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

В зависимости от модели вашего проекта и сферы деятельности может быть профессионально написать и даже развернуть код прототипа или проверки концепции. Это называется техническим долгом , и, как и любой долг, компания должна взять его в надлежащее время и вернуть в надлежащее время... с «выплатой процентов» в виде дополнительной работы.

Вашей профессиональной обязанностью было объяснить своим менеджерам, что такое технический долг, даже если вы не умеете пользоваться техническими терминами. Это их право и обязанность принимать решения о приемлемом уровне долга, даже если они не понимают технических деталей. Им платят, чтобы сбалансировать риск, например, между опозданием на рынок и увеличением затрат на техническое обслуживание. (Конечно, все было бы иначе, если бы стандарты качества регулировались профессиональными властями или устанавливались законом.)

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

  • Объясните ограничения вашего текущего кода. Вы можете даже ссылаться на документы с требованиями. UX написал в спецификации XY, что типичный список содержит менее 10 записей. Таким образом, пузырьковая сортировка вполне адекватна.
  • Объясните, почему что-то не было сделано технически . Все еще используем Java 1.7, потому что мы не можем использовать библиотеку X более новую, чем версия YZ, и она не будет компилироваться с 1.8.

Что этично?

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

Также обратите внимание, что эти разные системы редко соглашаются в том, что вы должны делать, и вам решать, что наиболее важно. Есть много, много, что я не включаю здесь.

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

Деловая этика

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

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

Конфуцианская этика

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

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

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

Утилитарная этика

Эта система находится в традициях Джона Стюарта Милля. Он утверждает, что правильным действием является то, которое приносит наибольшую «полезность» — меру счастья, которая не обязательно является объективной или эмпирической. Цель состоит в том, чтобы достичь наибольшего счастья для большинства людей.

(Не по теме: у «Субботних утренних хлопьев для завтрака» есть забавный комикс об этом.)

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

Кантианская этика

Иммануил Кант. Громкое имя в этике, и его материал быстро углубляется в абстракцию. Краткое изложение его идей состоит в том, что что-то действительно правильно и хорошо только тогда, когда оно не соответствует требованиям. Таким образом, цель не оправдывает средства, равно как и средства не оправдывают цель — каждый должен стоять сам по себе. В этом смысле единственное этически значимое соображение при принятии решения о мотивах поступка. Мотивом, предложенным Кантом, были долг и обязанность.

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

Прагматическая этика

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

Недостатком этого является то, что он описывает, как принимаются этические решения, и не очень предписывает, как принимать этические решения. Но это предполагает, что решения о том, что правильно, а что неправильно (например, ваш комментарий ...against my better judgment...), больше не принадлежат вам. Право и неправота этих решений принадлежат обществу, от имени которого ваша компания принимает решение, от имени которого вы сами принимаете решение.

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

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

Этика заботы

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

С этой точки зрения, профессионализм в данном сценарии даже не имеет значения. У вас есть кто-то, кто унаследует ваше положение, и вы не собираетесь помогать ему. Этическая осторожность предполагает, что вы должны сделать все возможное сейчас, чтобы дать им то мастерство, которое вы сейчас имеете над исходным кодом. Это включает в себя объективные знания, которые можно использовать в анализе, а также субъективные знания, которые можно использовать в суждениях.

Вывод

Ответить неясно. Читайте, думайте, комбинируйте, оценивайте.

Ничто из этого, кажется, не отвечает на вопрос. Я не минусовал, и вы, очевидно, приложили много усилий, чтобы написать это, но, честно говоря, это больше напоминает мне экзистенциальные комиксы , чем что-либо еще, просто с точки зрения разрыва реальности между этими философами и реальным миром. (Кстати, комикс, который я привел, очень забавный.) :)
Честно говоря, я озадачен этим ответом. В частности, был задан вопрос, этично ли оставлять комментарии, которые являются субъективными или основанными на мнении. Итак, я перечислил некоторые четко определенные этические системы, дал краткое описание каждой из них и то, как они применяются. Как это отключено?
Основной вопрос – это вопрос да/нет. Это действительно «должен/не должен», и разные этические системы (и их философские предпосылки) в лучшем случае случайны, в худшем — совершенно неуместны. И, на мой взгляд, ни одна из этих «этик» не имеет четкого определения, удовлетворяющего инженера. Ни один из этих философов не дает удовлетворительного инженерного определения «правильного», «неправильного», «хорошего», «злого» или даже самого слова «этика», которое можно использовать для получения предсказуемого результата. Никто не указывает, каков предполагаемый результат . Но это выходит за рамки простого комментария к ответу.
+1 Я думаю, что это очень хороший ответ. Все лучшие ответы - это всего лишь мнение одного человека, и ОП действительно использовал слово «этический», которое по какой-то причине большинство людей переводит в своих головах во что-то другое ...
В данном случае мне кажется совершенно очевидным, что вопрос задан с точки зрения разработчика программного обеспечения, желающего избежать неэтичных действий в контексте трудоустройства. Редко бывает неэтично сообщать важную фактическую информацию соответствующим людям.

Разработчик, который будет поддерживать этот код (будь то вы или другой человек), не получит никакой выгоды от таких замечаний, как «вопреки моему здравому смыслу» и «извините, если вам нужно поддерживать это». Комментарии, которые вы оставляете, должны быть полезны для приложения, в этом их цель.

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

Примечание разработчика. Этот процесс может прерваться при увеличении объемов данных.

Вы определили точную причину/место поломки? Добавьте это.

Было бы предпочтительнее использовать массовый экспорт, однако в то время это было невозможно.

«Было бы предпочтительнее» в лучшем случае субъективно. Просто упомяните, что массовый экспорт потенциально может помочь решить/смягчить проблему.

Существует настройка журнала ошибок, чтобы предупредить, если этот процесс выполняется слишком долго и его можно найти в месте X.

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

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

Комментирование и обеспечение корпоративной памяти настолько профессиональны, что люди должны делать это чаще.

Разница между вашей первой и второй версиями - первая эмоциональна ("ВАХ! ОНИ ДОЛЖНЫ СДЕЛАТЬ ЭТО, НО НЕ БУДУТ, ТАК ЭТО ВСЕ УМРЕЕТ!"). Второе более фактическое, это знания, которые им нужны, которые могут быть ситуативными и могут быть нарушены, и что можно сделать технически, и что вы хотите, чтобы они знали для своей собственной работы.

Нет приза что лучше.

Ваш вопрос путает "мнение" и "эмоциональность".

Мнение — это хорошо, вам платят за то, чтобы иметь представление о профессиональных областях: «Не идеально». «Выбор специального решения может вызвать проблемы, вот некоторая информация и то, как я бы предложил решить эту проблему». Или даже «Не лучший код класса, который мы написали, но времени мало, это исправление следует вырвать и основная проблема решается, когда мы можем убедить кого-то включить ее в бюджет ». Это все мнения. Даже если они резко или иронично изложены.

Эмоциональность бессмысленна и состязательна: «Дурочка босса потребовала этого для скорости, потому что ему наплевать на риск повреждения данных». «Надо было использовать библиотеку X, но тупицы в маркетинге хотят, чтобы она поторопилась, поэтому она, вероятно, сломается, мне приходилось постоянно исправлять ее, и мои заметки, как это сделать, находятся в файле Y на случай, если это кому-то еще понадобится». (Хорошо, все сильно преувеличено!)

В ваших примерах ключевая фраза "вопреки моему здравому смыслу". Значение (или, вероятно, будет прочитано как) «ВАХ, КАКИЕ ИДИОТЫ!» Вот что делает ваш первый эмоциональным. Еще несколько вещей, но это главное. Ничего не добавляет, кроме "Я РАЗБИЛСЯ OFFFFFF И ХОЧУ ЧИТАТЕЛЯ ЗНАТЬ ЭТО"

Увидеть разницу?

Да, пожалуйста, оставляйте комментарии. Даже если это только для того, чтобы объяснить, почему что-то было реализовано. Если какая-то часть кода выглядит довольно странно, но была конкретная причина сделать это таким образом, было бы очень полезно узнать, почему. В противном случае следующий парень рискует «исправить» странный код только для того, чтобы столкнуться со списком ошибок.

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

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

Как поясняется в разделе «Чистый код» , комментарии со временем портятся, поэтому наличие таких комментариев недопустимо. Кроме того, комментарии также воспринимаются как шум: слишком много комментариев, и вы, должно быть, делаете что-то не так.

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

Комментарии могут сгнить, но, по крайней мере, они будут найдены, в отличие от совершенно отдельного документа.
@PeterTaylor Вы имеете в виду что-то вроде этого: thedailywtf.com/articles/A_Collection_Of_Comments ?
Чистый код говорит: «Не комментируйте то, что вы делаете; комментируйте, почему вы это делаете». Комментарий, объясняющий алгоритм, можно считать шумом; комментарий, объясняющий, почему был выбран именно этот алгоритм, почти всегда полезен.
Первый абзац в порядке, но я не согласен с «написать отдельный документ». Я хочу видеть объяснение в многострочном комментарии сразу над классом или функцией алгоритма, даже если комментарий занимает больше места, чем код, следующий за ним, и даже если (точнее: особенно если) алгоритм супер- сложный и комментарий занимает несколько страниц.
@ScottMermelstein не стесняйтесь оставлять меньше комментариев о том, «что» и больше о том, «почему», но, пожалуйста, не оставляйте нулевых комментариев о том, «что», если это сложно и, возможно, потребуется поработать над ним когда-нибудь. Вы не настаивали на нулевых комментариях "что", но я просто хочу быть уверенным.
Этично ли включать комментарии к коду, основанные на мнении, для будущих разработчиков?
СпросиСетьПолитика конфиденциальности1y, 0v