Мой босс хочет рассказать по-английски объяснение нашего кода

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

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

Просили кого-нибудь сделать это раньше?

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

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

Это не разумный запрос, не так ли?


UPDATE

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

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

В конце концов, все стороны были удовлетворены, и мы продвинулись дальше.

155 голосов | спросил 7 revs, 4 users 54%
Billy Moon
1 Jam1000000amThu, 01 Jan 1970 03:00:00 +030070 1970, 03:00:00

30 ответов


160

Нет , это не разумный запрос!

РАЗГОВАЙТЕ ЕГО ИЗ ЭТОГО , или пусть кто-то еще из него выйдет из него, во что бы то ни стало. Это иррациональная идея, которая, несмотря на то, что она стоит дорого, никогда не должна быть выполнена. Обзор функций и подпрограмм является разумным, но «объяснить» каждую строку кода нет. Для него было бы более полезно научиться читать язык в руке, чем делать это.

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
150

У вас есть проектные документы ? Это английское объяснение того, что делает код. Менеджменту не-программирования не нужно больше.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
113

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

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

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

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

С положительной стороны, может быть, вы можете получить новый анти-шаблон, названный в честь вашей ситуации? Как насчет «Грязного венгерского разговорника» против шаблона, после того, как Монти Пайтон пропустит, где табак-консультант пытается общаться с кем-то, кто не говорит по-английски, используя венгерский разговорник с комически ложными переводами?

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
91

Сесть с ним и поговорить с ним через 10 строк кода. Объясните каждую деталь, пока вы оба не согласитесь, что понимает ее так, как он хотел.

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

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
43

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

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
32

Это очень просто:

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

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

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

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

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
25

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

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

Некоторые существующие решения, в зависимости от вашей платформы:

  • C #: sandcastle
  • Java: javadoc
  • "C ++, C, Java, Objective-C, Python, IDL (Corba и Microsoft flavors), Fortran, VHDL, PHP, C # и до некоторой степени D." : doxygen
ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
16

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
15

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

  1. Сообщите ему, что это займет столько же времени, как и для вас, чтобы вы могли его кодировать в первую очередь (не стесняйтесь делать это дольше.).
  2. Спросите его, насколько актуальным должен быть этот документ. Сообщите ему, что все изменения в кодировке теперь будут занимать не менее двух раз.
  3. Если вы или кто-либо еще обнаружите какие-либо ошибки, спросите его, следует ли вам исправить их сейчас или дождаться, когда вы закончите кодирование psuedo. Напомните ему о # 1 и amp; # 2.

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

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
12

Почему?

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

Это потому, что ...

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

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

Update

На основе комментария Mikey's, возможно, я сказал об этом немного грубо. Я не имею в виду, что вы должны буквально сказать «зачем вам это нужно?», Просто вы должны найти это . Формулировка и тон голоса имеют большое значение. В частности, вы можете сказать что-то вроде:

  

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

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

Если нет, начните полировку своего резюме. :)

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
10

Похоже, это хороший шанс попробовать грамотное программирование. Погугли это. :)

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

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
10

Даже перевод строки за строкой не будет эффективно передавать значение каждой строки кода. Программисты, понимающие строку кода, всегда находятся в контексте многих факторов. Входите во что-то вроде многопоточного кода, и английский перевод не будет иметь никакого смысла, чем исходный код. Подумайте о функциональности, которая распространяется между несколькими функциями /файлами. Некоторый код не имеет абсолютно никакого смысла, не объясняя большого количества другого кода. Попытайтесь объяснить разные части, участвующие в инъекции зависимостей «по очереди», и вы поймете, что я имею в виду. Почти все, что выходит за рамки процедурного кода функции Бога, потребует обширного знания в области программирования только для понимания английского перевода. Кроме того, посмотрите на что-то простое, как утверждение решения if /else. Постепенно нет строки, поскольку следующая строка зависит от данных времени выполнения. Следующая строка может быть одной из нескольких возможностей. К тому времени, когда вы объяснили, что делает ваше приложение, вы превратили своего PM в программиста, и вы оба на 5 лет старше.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
10

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

Он быстро узнает, что получает больше, чем рассчитывал, что меня огорчает, потому что я как объясняю вещи : -)

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
10

Когда вы ссылаетесь на своего «Босса», это «средний менеджер, отвечающий за вас /вашу команду»? или Владелец вашей компании? Платили ли вы «по часам» или «по зарплате»?

ЕСЛИ ваш босс является менеджером среднего уровня, который подотчетен, ГОВОРИТЕ К ЕГО БОССУ, отметьте, что для удовлетворения требования вашего босса ваша производительность для компании будет сокращена до 1/3 того, что она может быть.

ЕСЛИ ваш босс «тот, кто подписывает чеки», объясняет ему одно и то же, более дипломатично. Ваша работа перешла от «Напишите код» на «Напишите код, напишите объяснение кода, объясните объяснение».

введите описание изображения здесь>> </p></body></html>

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
9

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
8

Тот факт, что ваш босс желает потратить некоторое время на понимание кода, который вы написали, вы можете использовать для своей выгоды. Попробуйте познакомить его с Огурцом: http://cukes.info/

и сделайте, чтобы ваш босс написал BDD-тест для вас в будущем.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
6

Он не должен беспокоиться об этом. Скажите ему, что в процессе разработки программного обеспечения возможны изменения. Дизайн мероприятия может быть изменен. Расскажите ему о скрытии информации, инкапсуляции и абстракции.
Он, как часть вашей команды, как клиент вашего кода, в более широком смысле, должен работать только с четким, высоким уровнем абстракции того, что делает ваш код. Точно так же любой слой вашего кода работает с другим слоем чужого кода. Зная больше, чем это, только замедлит его и рискнет делать предположения, основанные на внутренней работе вашего кода. Эти предположения перестанут держаться, когда вам придется изменить свой код, что становится проблемой, если он построит какую-либо систему или процесс, основанный на них.
А также выполнение этой работы уменьшит вашу эффективность. Мало того, что вам придется делать последующие изменения в двух разных местах, но это также негативно повлияет на ваш моральный дух работы, что еще больше снизит ваш результат.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
6

Красота английского - это то, что прекрасно увязывается. Если вы используете это в своих интересах, вы, возможно, никогда не захотите снова обращаться к подобным запросам. Я бы взял небольшой фрагмент кода в качестве образца, но тот, который очень абстрагирован и совсем не понятен. Затем я напишу комментарии на техническом английском, как будто вы пишете его в главе в книге программирования. Чем дольше и сложнее следовать, тем лучше. Скажите ему, сколько часов потребовалось вам для документирования этой функции. Затем объясните, что это всего лишь 1/10 из 1% (используйте фактические цифры, основанные на строках кода, если можете, они, вероятно, хуже этого) фактической базы кода. Когда он понимает, что он не знает, что говорит английский перевод, и что для этого уровня документации потребуется около 20 000 человеко-часов, он отступит довольно быстро. Но будьте очень искренне пытаясь выполнить его задачу. Не пытайтесь это сделать, если вы не можете снять это, и он подозревает, что вы играете с ним.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
6

Это выглядит как кандидат на специальную праздничную тему с надписью Dilbert ! На первый взгляд его просьба не имеет разумного звука .

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

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
6

Принесите его в свой офис и дайте ему экскурсию по вашему коду.

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

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

Это случай, когда умиротворение работает лучше, чем истирание.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
6

Было бы очень приятно, если бы у нас был переводчик «Language X to English», который делает это. Тогда можно было усмехнуться и сказать, без проблем, босс, вы получите это через минуту. И затем приходит почта с несколькими мегабайтами текста, который гласит:

  • Пусть a - новый целочисленный массив с 20 элементами.
  • Пусть x является переменной для хранения целых чисел.
  • Установить x в 0
  • Пока значение x меньше 20, выполните то, что предписано в следующих двух строках.
  • установите элемент массива a с индексом x в результат вызова nThPrime с аргументом x + 1
  • увеличить x на 1
  • ....

Другим вариантом было бы предложить программирование в Шекспира впредь.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
5
  

Мой босс хочет рассказать по-английски объяснение нашего кода

Tough.

  

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

Если он не программист, он не должен читать код. .

Предоставьте документацию высокого уровня.

  

Это не разумный запрос, не так ли?

Нет.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
4

Как программист, у вас действительно есть «два» задания.

Во-первых, это создание хороших программ. Во-вторых, «продавать» их клиентам внутри и вне компании.

Запрос вашего босса «вредит» вашей первой работе. Для документирования ваших программ требуется больше времени. С другой стороны, он на самом деле заставляет вас усердно работать над вашей «второй» работой.

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
4

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

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
4

Вероятно, этот запрос - хорошее время для изучения таких вещей, как ANTLR . Возьмите ANTLR, возьмите грамматику своего языка, проанализируйте весь код, который у вас есть, перейдите в AST , основанные на описаниях для каждого узла, поэтому i++ описывается как increase i by 1 using postfix increment operator. Это должно быть действительно смешно. Ваш босс может также захотеть, чтобы этот инструмент был включен в скрипт сборки, поэтому каждый раз, когда вы вносите какие-либо изменения, он получит электронную почту ~ 20 МБ, описывающую, что делает новая версия.

P.S. Просто шучу, он идиот.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
3

Хотя я согласен с тем, что это необоснованный запрос, ваш босс может оценить что-то вроде вывода Docco , который отделяет ваш код и поэтапные или предложения по предложениям от двухэтажного HTML-вывода с кодом на одной стороне и прозой на другом. Разумеется, вы должны сами вводить комментарии, но презентация довольно приятная ИМХО, даже для нетехнических читателей. См., Например, пошаговый раздел комментариев аннотированного кода для Underscore.js . Существуют также версии сценариев Python и shell.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
3

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

Если дело доходит до «моего пути или шоссе», лучше проверьте свой газ сейчас.

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
3

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

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
2

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

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

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

// Set s to the first address in the server list
server_info *s = cmd->servers;
// Loop until s is NULL
while (s) {
    // call the server's init function passing our current ID and address
    s->init(proc->id,*addr);
    // call log::info with our custom message
    log::info("Starting server %s",s->name);
    // Set s to the value returned by the server's next() function
    s=s->next();
} // end of loop

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

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

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04
1

ИМХО ... если он отвечает за выполнение поставленной задачи, он должен знать, как это работает ...:)

ответил GlenPeterson 6 J0000006Europe/Moscow 2013, 19:51:04

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132