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

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

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

Кто-нибудь просил сделать это раньше?

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

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

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

ОБНОВИТЬ

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

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

В итоге все стороны остались довольны и мы пошли дальше.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Это действительно очень просто:

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

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

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

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

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

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

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

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

• C #: замок из песка
• Java: Javadoc
• «C ++, C, Java, Objective-C, Python, IDL (варианты Corba и Microsoft), Fortran, VHDL, PHP, C # и в некоторой степени D.» : doxygen

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

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

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

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

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

Почему?

Строковый комментарий не обоснован, но вот что я спрашиваю: зачем вам это?

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

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

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

Обновить

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

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

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

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

Звучит как хорошая возможность попробовать грамотное программирование. Погугли это. :)

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

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

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

Так как я раньше преподавал программирование, я был бы только рад попробовать.

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

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

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

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

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

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

и заставьте своего босса написать тест BDD для вас в будущем.

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

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

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

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

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

Приведи его в свой офис и проведи по твоему коду.

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

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

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

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

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

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

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

Tough.

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

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

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

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

Нет.

Как программист, у вас действительно есть две работы.

Первый заключается в создании хороших программ. Второе - «продать» их клиентам внутри и за пределами компании.

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

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

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

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

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

PS Шучу, он идиот.

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

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

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

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

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

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

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

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

// 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

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

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

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