Как перестать комментировать всё подряд?

Question

[IvanIF]

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

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

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

Так я постепенно добавлял комментарии, пока не ударился в другую крайность — комментариев встало слишком много. В этой крайности я и нахожусь сейчас. В какой-то момент я начал ловить себя на мысли о том, что 20% времени пишу код, а оставшиеся 80% обдумываю и пишу комментарии. Дело доходит даже до вот таких крайностей:

// Переменная для хранения информации о возможности клика по кнопке «Зарегистрироваться»
// true — клик разрешён, false — клик запрещён
var can_click_su = true;

У меня в голове как будто засела навязчивая мысль, которая говорит: «Закомментируй, потом не поймёшь!».
Как с этим бороться???

Comments

[iBird Rose]

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

[Василий Банников]

var can_click_su = true;
А ведь можно было бы просто назвать переменную is_click_at_sign_up_button_allowed и не пришлось бы писать комментарий на две строки.

[Vitsliputsli]

Нормально комментируете, вряд ли назначение переменной очевидно без этого комментария. Как написано выше правильнее выбирать хорошие имена для переменных, но не всегда это просто и очевидно, да и когда название переменной становится слишком длинным тоже не хорошо.
Ну разве что, вместо "true — клик разрешён, false — клик запрещён" достаточно указать что это тип bool. И посмотрите как оформляются комментарии к переменным в вашем языке.
Кодирование - это только один из этапов разработки, лишь у новичков уходит на него 95% времени. Возможно вы начали это понимать.

[WbICHA]

Как с этим бороться???

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

// Переменная для хранения информации о возможности клика по кнопке «Зарегистрироваться»
// true — клик разрешён, false — клик запрещён

Что спокойно записывается в самоописываемое название:

canClickSignUp
isSignUpActive
isSignUpAvailible
// and etc.

[WbICHA]

И что за язык? Если жс, то по какой причине используешь комментарии вместо жсдока?

[IvanIF]

жс

жсдока

что это?
JavaScript

[WbICHA]

IvanIF, я что, похож на гугл?

[irishmann]

WbICHA, пункты 3.3, 3.5 правил сайта прочитайте, это относится не только к созданию вопросов.

[WbICHA]

irishmann, прочитал, какое отношение они имеют ко мне?

[irishmann]

WbICHA, еще раз прочитайте

[WbICHA]

irishmann, прочитал ещё раз, какое отношение они имеют ко мне?

Answer 1

[Алексей Ярков]

Писать код так, чтобы он сам себя документировал.
Давать осмысленные имена переменным и функциям, пусть длиннее, зато читабельнее.
Почитать про архитектуру, паттерны.
Рекомендую "Чистый код" Р. Мартин. Там эта тема поднимается.

Answer 2

[Uno]

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

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

Answer 3

[D1os]

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

Button_status = "Highlighted"
window_current_x = 500
is_visible = False

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

def gcd(x, x2):
    # Нахождение наибольшего общего делителя

P.s., все примеры на Python, если что.

Answer 4

[cicatrix]

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

Answer 5

[Denis Fedorets]

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

Answer 6

[Saboteur]

// Переменная для хранения информации о возможности клика по кнопке «Зарегистрироваться»
// true — клик разрешён, false — клик запрещён
var can_click_su = true;

Меняешь на

var can_click_register_button = true;

Answer 7

[Foxbator]

var registration_button_enable = true;

Answer 8

[Владислав]

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

Answer 9

[mkone112]

Выломай слеш из клавы.

Answer 10

[Лев Забудкин]

По сути это философский вопрос, но я бы рекомендовал пропить курс витаминов, особенно B и попить Ноотропил с Глицином.
Месяца 3.
И потом всё придёт в норму.
Последнее особенно полезно при учёбе и умственных нагрузках, но когда витаминов B не хватает, то бывает ломота в костях.