Как я могу попросить моего босса (вежливо) прокомментировать его код?


72

Меня обучает мой начальник (я только что закончил школу, и он хотел кого-то с небольшим опытом программирования, поэтому он выбрал меня, чтобы обучить меня тому, на чем специализируется эта компания) и начал работать с приложениями ASP.NET MVC , некоторыми HTML и CSS , Я в порядке с вещами веб-дизайна, которые он дает мне (это довольно просто понять без разъяснений).

Но, например, он дает мне задачу, связанную с ASP.NET MVC, он объясняет это очень хорошо. Но он ничего не объясняет в коде, который он только что дал мне. (Мы используем контроль исходного кода в Visual Studio 2013 ), так что это буквально сотни строк кода, без какой-либо информации о том, что он должен делать. Код, который я вижу, - это код, который я никогда не видел прежде, поэтому действительно трудно попытаться понять.

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

Так что только то, что поможет мне, пока я не овладею вещами, как я могу попросить моего босса добавить комментарии в свой код, который он дает мне, но вежливо?


2
Комментарии не для расширенного обсуждения; этот разговор был перенесен в чат .
maple_shaft

1
Альтернативой запросу является использование инструментов индексации исходного кода и навигации, таких как SourceGraph .
Дан Даскалеску

Недавно я начал работать в команде, работающей над большим (> 100 тыс. Строк) приложением MVC5. Всего 150 юнит-тестов, и все они были добавлены мной за последние несколько месяцев. Несколько комментариев в коде в основном на других языках. Welcome to business programming :)
Марк К Коуэн

Такие вопросы, как «Как мне попросить X сделать Y», обычно лучше на рабочем месте, когда X привлекает коллегу.
Blrfl

Ответы:


130

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

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

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


185
+1 за «Сидеть перед тысячами строк кода, с которыми вы не знакомы, является нормой» - это никогда не появляется в курсах программирования и всегда появляется в работе.
pjc50

11
Спасибо, что дали мне надежду, я на самом деле думал просто бросить работу и поступить в университет или что-то в этом роде. Я говорил с ним некоторое время назад, и он сказал, что он очень впечатлен моим прогрессом, бла-бла-ха-ха .. @ pjc50 Я полностью согласен с вами в основном после прохождения теста и урока. Я, вероятно, узнал не больше за последний месяц, чем за 3 года, которые я провел в школе!
Эйдан Куинн

9
Именно так. Программирование как торговля эффективно требует ученичества (возможно, самообучения), в то время как курсы CS могут содержать очень мало фактического программирования. Они симбиотические, но не одно и то же. Вам не нужно поступать в университет, чтобы стать отличным программистом, но его намного легче получить, даже если курс мало связан с работой, на которую вы претендуете.
pjc50

11
@AidanQuinn, синдром самозванца ( en.wikipedia.org/wiki/Impostor_syndrome ) может сильно ударить в начале новой работы и, тем более, в начале вашей первой работы. Если он говорит, что у тебя все хорошо, поверь ему на слово.
Celos

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

75

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

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


Несколько моментов, которые следует иметь в виду:

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

  2. Хороший начальник максимально открыт для перерывов и вопросов. Хороший сотрудник старается изо всех сил, чтобы свести к минимуму перерывы и вопросы. Будьте в курсе этого.

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

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

  5. Если вы уверены, что дополнительные комментарии значительно помогут коду, спросите своего босса. «Мне трудно понять, что происходит в некоторых местах. Когда я все выясняю, вы не возражаете, если я добавлю комментарии?» Может быть, он ненавидит комментарии. Может быть, ему это понравится. Может быть, он будет безразличным.

В конце концов, однако, возможно, что через пару месяцев вы вспомните вопрос об этом и подумаете: «Да, мне интересно, с чем у меня была проблема? Это не так уж плохо. Хм, ну, неважно».


6
Мне особенно нравится пункт 3. Иногда полезно написать быстрое электронное письмо из двух строк с просьбой, чтобы он пришел, чтобы помочь вам с проблемой, даже если он просто сидит в офисе в нескольких футах от вас. Это позволяет ему определить, когда он будет готов прерваться, и даст вам больше времени для составления более полного списка вопросов до того, как обсуждение действительно начнется.
Фил

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

3
@kmote, у меня много незаданных вопросов о переполнении стека, которые произошли точно так же :)
Пол Дрейпер

18

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

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

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


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

2
@BasileStarynkevitch: конечно, чтобы избежать риска что-то сломать, он может сначала добавить комментарии в отдельную ветку и попросить своего босса просмотреть комментарии, прежде чем они будут объединены в ствол.
Док Браун

2
@DocBrown Работа в отдельной ветке в целом является хорошей стратегией, но если добавление комментариев что-то нарушает, то я бы сказал, что у кодовой базы есть большие проблемы ......
CVn

1
@ MichaelKjörling: на самом деле, это то, что ОП должен обсудить со своим боссом. Использование другой ветки имеет два преимущества: оно позволяет избежать случайных разрывов, сделав опечатку, например, слишком большое удаление одной строки при удалении устаревшего комментария, и заставляет босса просматривать комментарии.
Док Браун

@ MichaelKjörling - это не то, что комментарии что-то нарушают, а комментарии должны соответствовать реальному коду.
Хьюго Цинк

8

Во-первых, пусть это будет примером для вас, чтобы правильно комментировать ваш код, кузнечик!

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


5

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

Будьте тем изменением, которое вы хотите увидеть в мире.

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

  • Вы активны, а не нытье.
  • Вы подаете хороший пример. В лучшем случае ваш начальник / команда увидят преимущества и последуют их примеру.
  • Некоторые из комментариев, вероятно, скажут /* Mystery parameter 3 */или /* 2015-02-09 AidanQuinn: Is this code ever called? */- это возможность для ваших коллег либо правильно документировать код, либо исправить скрытые ошибки.
  • Если во время проверки перед фиксацией обнаружится, что написанный вами комментарий является неточным, то ваши коллеги теперь знают, что код неясен.

Воздержитесь от переписывания или рефакторинга, пока вы делаете это, и введение комментариев должно быть практически без риска. Если вы что-то переписываете, сохраните эти изменения как отдельные коммиты.

(Однако, прежде чем приступить к этому проекту, убедитесь, что ваши ожидания в отношении комментариев разумны. Если ваша идея хорошо прокомментированного кода выходит за рамки нормы ( Пример 1 , Пример 2 ), то вы будете только дурачить себя.)


5

Я бы не стал просить дополнительные комментарии, но вот несколько идей для вас:

  1. Запланируйте встречу с вашим боссом и попросите его пройти код на высоком уровне. Это должно начать вас. Я ожидал бы от нескольких часов до полдня, чтобы вы могли набрать скорость. Это должно включать общий дизайн, используемые шаблоны и т. Д.
  2. Создайте проект тестов и начните писать модульные тесты для кода, это поможет вам понять его, не влияя на него. Вы также можете найти некоторые ошибки!
  3. Отладка кода по мере необходимости, чтобы понять определенные области.
  4. Возьмите улучшение или исправьте отставание и работайте над ним.

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

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


2

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

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

Кроме того, я должен согласиться с @AK_, который сказал, что вам не нужны комментарии в C #. Это может быть не на 100% правильно (я чувствую, что есть области, где комментарии, безусловно, помогают, например, код с интенсивным отражением), но по сути это так. Если вы пишете действительно «чистый код» с хорошо названными методами и переменными и имеете много маленьких «кусочков» кода, они будут почти полностью ненужными. Каждый раз, когда я до сих пор чувствовал потребность в комментариях при чтении кода, то после того, как я понял, что он делает, я был очень недоволен тем, как это было сделано, и подумал, что это могло бы быть намного яснее, в первую очередь, благодаря хорошему рефакторингу. Изменить: я специально говорю о комментариях C # здесь, а не документации (будь то отдельная документация или комментарии XML), так как я думаю, что документация всегда важна.

  • Определите, в чем именно заключаются ваши проблемы, и можете ли вы классифицировать их. То есть у вас все еще есть проблемы с самим языком или вы не понимаете определенный синтаксис (например, лямбда-выражения и LINQ в целом или Reflection)? Если вы не понимаете строки кода, вы не поймете, что делает весь метод / блок, поэтому комментировать его будет сложно. Скорее, получите хорошую книгу («C # in Nutshell», она была для меня, но я слышал, что «C # in Depth» также впечатляет) и прочитайте о том, с чем вы сталкиваетесь. Классификация этих проблем заранее облегчает эту задачу, поскольку вы можете сразу заполнить «большие пробелы» или даже спросить своего босса об этом, так как теперь это не слишком много вопросов, а скорее объяснение одного предмета или наиболее часто используемых конструкций, чтобы вы могли может получить огромный «импульс»

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

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

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


1

Вы, вероятно, не собираетесь заставить его изменить свой стиль.

Что вы можете сделать, это задать много вопросов и записать ответы.

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

Удачи!


1

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

Я подал заявку на работу для веб-разработчика, и они сразу же положили меня на задний план веб-программирования. Когда босс показал мне базовый API для REST-приложения узла, я подумал, что я его выброшу. Я никогда не видел функций с обратным вызовом и таким странным синтаксисом. И я спрашиваю моего босса, есть ли у меня проблема, если я ничего не понимаю в коде. Он грустный нет, он грустит, что у меня есть 1 месяц, чтобы выяснить это, и в то же время я сделаю CMS для тестирования меня с другим фронтменом.

Ну, и я пошел 1 строку кода в то время и Google все, что я не знаю. Итак, прошла 1 неделя, и я был достаточно знаком с кодом, чтобы можно было покрасить его передним эндером. Мой код в начале был дерьмом, но через 3 месяца после этого! Я пишу лучше и быстрее, чем наш разработчик программного обеспечения!

Я полагаю, что вы никогда не прекращаете учиться! Мой девиз -> Продолжай учиться и сохраняй спокойствие :) Не полагайся на босса, будь независим и спрашивай его напрямую, но только самые сложные проблемы. Потому что вы будете счастливы после того, как разберетесь со своим собственным исследователем. И помните, когда вы перестанете учиться чему-то неправильному, научитесь каждый день тому, как быть хорошим программистом.

Если вы научитесь у босса, вы никогда не станете лучше, чем он, установите свой собственный стандарт, изучите слепую печать, VIM или плагин VIM для вашей IDE, Linux wmii, так что вы когда-нибудь выйдете за пределы босса и будете лучше его!


этот пост довольно трудно читать (стена текста). Не могли бы вы изменить его в лучшую форму?
Комнат

Извините за мое невежество :)

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

1
Прошу прощения, я делаю это утром перед работой, и у меня не так много времени на руках, цель состоит в том, что владелец вопроса увидит, по вопросам, которые меня не волнуют :)

0

Как инженер-программист с 20-летним стажем, в основном работающий над вопросами безопасности (SF-PD), я должен сказать, что ваш начальник может не быть тем, кем вы хотите быть вашим примером. Отсутствие комментариев является признаком либо самоучки-программиста-любителя, который так и не научился правильно выполнять работу, либо неопытного инженера. Или, может быть, инженер, у которого просто нет времени - сроки и целесообразность могут сделать ужасные вещи с вашим кодом! ;) Это определенно антишаблон для каждого компетентного инженера-программиста.

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

Самое основное, что в комментариях не должно быть сказано, что делает строка кода. Иногда комментарии о том, что делает функция, тоже излишни (особенно в C #). Чрезмерное комментирование может быть столь же неэффективным (и указатель на недостаток опыта), потому что вы не можете найти важные вещи в шлаке. Как новичок, вы, возможно, все еще работаете над выяснением «что» в коде, и для этого вам просто нужно прочитать и понять, что он сделал.

Однако для комментариев важно, что они говорят, ПОЧЕМУ строка кода или функция делает то, что делает, где это может быть неочевидно. Вам нужно настроить модуль X перед модулем Y? Важно ли проверять код возврата, чтобы увидеть, был ли файл уже открыт, или мы сознательно игнорируем код возврата, потому что он был проверен где-то еще? «Почему» в коде будет иметь отношение ко всем, независимо от опыта, и это будет актуально и для него через 6 месяцев, когда он забудет о веской причине для того, чтобы сделать что-то определенным образом. Комментировать не только для других людей, но и для того, чтобы помочь вам в будущем.

Если вы хотите избежать раздражения своего босса, задавайте умные вопросы. Сосредоточьтесь на том, чтобы спросить «почему», и попытайтесь решить «что» сами (если это действительно неясно). Ни один хороший начальник не возражает против того, чтобы его задавали, если это не те вещи, которые вы могли бы найти в R-ing TFM. И ни один хороший инженер не будет возражать против того, чтобы его попросили сделать что-то, что значительно облегчит жизнь другому инженеру и при этом не потребует больших затрат. (Только не просите его засыпать комментарии на всей базе кода!;)


1
Первый абзац подразумевает, что начальник - и большинство из нас - некомпетентны, потому что он (как предполагается) не комментирует так, как должен. Это прискорбно, потому что остальная часть совета о том, когда и как комментировать, на самом деле довольно здравая. Большинство из нас, вероятно, согласятся с этим, если бы мы не были так расстроены с самого начала.
Джон М Гант

Последние три абзаца вашего ответа весьма полезны, @Graham. Пожалуйста, не позволяйте нескольким отрицательным голосам отговорить вас.
DavidS

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

@Superstringcheese: К сожалению, вы часто получаете отрицательные отзывы за то, что занимаете позицию, отличную от «Мама и яблочный пирог». Я не согласен с некоторыми из того, что вы сказали (не первый абзац! Это полностью верно для ИМО), - но вы все равно получаете принципиальное одобрение.
einpoklum - восстановить Монику

0

Находясь в аналогичной ситуации, я бы сказал,

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

  2. Это «норма», как указано в других ответах. Вы должны больше беспокоиться о том, с чего начать, как подходить и на чем сосредоточиться, чем пытаться сразу понять каждую строчку кода. Спросите своего босса о правильных инструментах и ​​способах отладки / пошагового выполнения кода. Подобные вопросы купят вам несколько очков.

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

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


0

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

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


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

@ Richremer Я думаю, что мы почти полностью согласны. Я стремлюсь к самодокументируемому коду с комментариями, где вещи становятся напряженными.
dkippers

0

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

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


0

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

  • Найдите что-то в коде, связанном с поставленной задачей. Обычно проще всего искать что-то, что видно пользователю, например, метку кнопки в графическом интерфейсе. Запишите, где вы его нашли. Это будет ваша точка привязки.
  • Теперь найдите код на расстоянии одного шага и запишите его. Кто создает кнопку? Какой код вызывается при нажатии кнопки?
  • Контроль исходного кода часто полезен для поиска кода, который находится на расстоянии одного шага. Узнайте, когда код, который вы просматриваете, был добавлен или изменен, и посмотрите, что еще было проверено в то же время и почему.
  • Повторяйте, пока не поймете, что достаточно, чтобы внести изменения, плюс еще один уровень глубже, чтобы убедиться, что вы ничего не пропустили.
  • Если вы застряли в какой-то момент, теперь у вас есть очень конкретный вопрос. Например, «Я не могу понять, откуда создается эта кнопка».

0

Вот мои $ 0,02 по этому вопросу. Я не предлагаю эксклюзивный ответ, многое из того, что было сказано здесь, весьма актуально.

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

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

Какая альтернатива, тогда? Несколько идей, в зависимости от обстоятельств.

Опция 1

  1. Потратьте время, чтобы понять часть его кода как X.
  2. Теперь подумайте о том, как разумно понять это неправильно .
  3. Скажите боссу (по электронной почте или за завтраком или что-то еще), что вы сейчас пытаетесь это выяснить.
  4. Добавьте комментарий о том, что не ясно, что означает код, но вы понимаете его как Y; попытайтесь сделать этот комментарий видимым для него - но не пытайтесь слишком сильно!
  5. Действуйте, предполагая Y - и убедитесь, что ваш начальник замечает ваши действия (чтобы вы не тратили много времени на работу из-за ложного предположения).
  6. Босс должен проявить инициативу, чтобы исправить вас. В этот момент скажите ему что-то вроде: «Мне бы очень хотелось, чтобы в этом коде было несколько комментариев, чтобы я не сделал неправильного предположения. Я исправлю комментарий, который я добавил для себя. этих фрагментов кода? У меня недостаточно опыта, чтобы понять точное намерение, и я всего лишь пару предложений, которые помогут. " Или что-то..

Вариант 2

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

Вариант 3

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


0

Так что только то, что поможет мне, пока я не овладею вещами, как я могу попросить моего босса добавить комментарии в свой код, который он дает мне, но вежливо?

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

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

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


0

Даже если есть способ задать это вежливо, есть две возможности того, что ваш начальник подумает о комментариях в своем коде:

  1. Либо эти комментарии в его коде было бы хорошо иметь, либо

  2. Эти комментарии в его коде не очень хорошая вещь.

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

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

Так что, если вы не готовы сделать это, вам лучше ничего не говорить.

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.