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

155

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

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

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

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

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

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


ОБНОВИТЬ

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

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

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

Billy Moon
источник
Заблокировано по историческим причинам, см. «Блокировка закрытых вопросов с наибольшим количеством голосов» для получения дополнительной информации.
Яннис

Ответы:

160

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

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

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

Ладья
источник
Интересно: иди почитай лекции Ричарда Фейнмана по физике. Вы найдете, что большая часть этого является тщательно сформулированным аргументом на английском языке (если X, то Y должен быть истинным, и, следовательно, Z ... и т. Д.). Маленькая математика. Суть в том, что вы можете объяснить вещи по-английски. ДОЛЖЕН ли ты - другой вопрос.
quick_now
1
@quickly_now - Читайте их давным-давно во время учебы в колледже. Неплохое чтиво. Я согласен, вы можете объяснить это - вы можете объяснить это на любом языке, когда человек, которому вы объясняете, уже понимает «абстракцию», стоящую за ней (код, математическое уравнение и его значение ...) // Если он этого не делает t - у вас будут проблемы с объяснением на любом языке.
Грач
4
@Rook - хорошая мысль. Объяснить квантовую механику примитивному племени, чей словарный запас ограничен тем, в каком направлении двигался Лось, было бы довольно сложно.
quick_now
Время от времени я могу получить «намерение» вашего менеджера на микроуправление. Но, если код был сам по себе очень понятным, он может просто прочитать его как текст на английском языке.
Арвинд Чинния
150

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

xtian
источник
15
Вот почему я указал: «Менеджеру без программирования не нужно больше».
Malfist
35
@Loren Pechtel: Я хотел бы зайти туда и посмотреть, как этот парень на самом деле читает страницы "Создайте целочисленную переменную с именем X. Установите ее на 0. Создайте целочисленную переменную с именем Y. Установите ее на 0. Создайте целочисленную переменную с именем Z". Установите его в 0. Создайте целочисленную переменную с именем X. Установите его на 0. Создайте целочисленную переменную с именем Y. Установите на 0. Создайте целочисленную переменную с именем Z. Установите на 0. Создайте целочисленную переменную с именем Вращение X. Установите его в 0. Создайте целочисленную переменную с именем Y вращение. Установите в 0. Создайте целочисленную переменную с именем Z вращение. Установите ее в 0. "...
FrustratedWithFormsDesigner
9
@Frustated С подсветкой синтаксиса намного проще! « [p32767, l21, c8] Увеличить pXна размер Integer. Увеличить Sumна значение, на которое указывает pX. Увеличить iна 1. Если значение iменьше 3, перейдите на страницу 32768, строка 17, столбец 42. В противном случае перейдите на страницу 32767. , строка 21, столбец 8. "
Матеин Улхак,
9
@muntoo, вам нужно встроить все эти функции, чтобы вам не приходилось перемещаться между страницами. В противном случае может возникнуть много проблем с возвратом в стек.
Кибби
15
@ Разочарованный: Так чей голос ты воображаешь? Я не могу определиться с Шоном Коннери и Морганом Фриманом.
бета
113

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

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

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

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

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

psr
источник
21
+1 за диагностику микроуправления. По моим собственным словам: вытащить f___ оттуда!
tdammers
@tdammers: к счастью, это то, что я могу сказать своему боссу. Он хороший парень, кроме того, что он босс!
Хелтонбайкер
5
Менеджер, который должен понимать каждую строку кода, называется программистом.
Джеймс П.
91

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

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

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

reinierpost
источник
57
Убедитесь, что после двух часов объяснения десяти строк он понимает, что для объяснения осталось 50 000 (или что-то еще) строк кода.
HLGEM
6
На самом деле очень разумный способ следить. Заставь его увидеть невежество его путей.
Кибби
4
@reinierpost: ваш метод чистый гений.
Хелтонбайкер
5
Если вы собираетесь это сделать, сначала скажите боссу, почему это вообще плохая идея, а затем продемонстрируйте. Если вы этого не сделаете, это может выглядеть так, как будто вы натягиваете на него «трюк» и ставите его в оборону.
nerdytenor
5
Никогда не говорите людям, что их идеи плохи !! Тем не менее, вы можете обсудить, что нужно сделать, чтобы их воплотить в жизнь, и, возможно, даже дать некоторые идеи для принятия ярлыков. Если это приводит их к заключению, что идея не была жизнеспособной, или превращает первоначальную идею в нечто совершенно иное, и они должны заметить это в какой-то момент, они пожмут плечами и скажут: это жизнь.
reinierpost
43

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

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

Пабло Санта Круз
источник
13
Даже с английским переводом непрограммист может очень хорошо поверить:/* and this line is transferring deposits to the correct account */ deposits.TransferAll(acctInfo);
IAbstract
15
Если босс «боится, что вы заставите свой код делать то, что он не одобряет или знает», это ничего не изменит для его страхов. Тот же человек предоставляет перевод, который написал код. Что мешает им лгать о том, что он делает? Здесь что-то еще происходит.
mmc
4
Кобол предназначался для чтения на английском языке.
oosterwal
1
Возможно, он пытается выяснить, что делает код, чтобы увидеть, согласен ли он с рассуждениями и, возможно, получить лучшие идеи. В любом случае, это не его работа, по крайней мере, так ...
heltonbiker
32

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

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

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

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

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

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

Джон Н
источник
как ваш менеджер принял ваше объяснение?
Джефф Мартин
1
Точно так же, как вы могли ожидать. ;) Однако, точка была сделана, и запросы прекратились. Я не знаю, было ли это потому, что я убедил ее в обоснованности моих аргументов или она решила, что это не стоит хлопот, и сдалась.
Джон Н
25

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

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

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

  • C #: замок из песка
  • Java: Javadoc
  • «C ++, C, Java, Objective-C, Python, IDL (варианты Corba и Microsoft), Fortran, VHDL, PHP, C # и в некоторой степени D.» : doxygen
Стивен Эверс
источник
Поскольку есть Pas2Dox, добавьте Delphi в список doxygen ;-)
Fabricio Araujo
Перейти к ссылке Sandcastle. Выглядит впечатленным. Нажмите вкладку «Документация». Смотрите сообщение «Этот проект еще не имеет документации». Смотреть меньше, чем впечатлило.
Каз Драгон
16

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

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

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

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

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

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

оборота Джеффо
источник
7
мы должны быть осторожны, чтобы охарактеризовать кого-либо как "идиота". Хотя нам, как программистам, лично это нравится, я не думаю, что это профессионально, и любой запрос любого менеджера, каким бы странным он ни был, следует рассматривать исходя из его достоинств.
funkymushroom
6
@funkymushroom: Преимущества этого запроса в том, что он идиот.
DeadMG
3
@funkymushroom - я думаю, что мы можем позволить немного легкомыслия на этом сайте. В конце концов, вы идете мимо funkymushroom.
JeffO
2
@Джефф: Точка хорошо принята. Я ни в коем случае не палка в грязи. Однако есть два вида «идиотов». «Злобный идиот» и «Невежественный идиот» и я работали с обоими. Первое следует игнорировать, он опасен для нашей карьеры, а второе может быть хорошим союзником, поэтому мы должны его учить.
funkymushroom
@funkymushroom - согласен, так что я достал его.
JeffO
12

Почему?

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

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

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

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

Обновить

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

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

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

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

Натан Лонг
источник
-1 для этого ответа: Если вы хотите сохранить свою работу (или, по крайней мере, оставить ее добровольно), вам не следует спрашивать такого начальника «почему»? Это то, что должно быть утончено, как и предлагали другие.
вектор
3
Я не согласен с комментарием Майки. Слепое следование приказам глупо. Спрашивая «почему?» При каждом запросе я экономил бесчисленные часы ненужной работы и экономил кучу денег в процессе. Это называется консультация, и те, кто не боятся своих боссов, делают это свободно и с большим эффектом. Когда люди, которые работают на меня, предлагают что-то, я также спрашиваю их «почему?» также. В обоих случаях он ищет оправдания, и это вполне приемлемо.
Совиут
10

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

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

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

оборота JohnL4
источник
Я посмотрел на странице Википедии. Это напоминает мне о «структурированном <вставить человеческий язык здесь>», который я видел во время учебы. Вы используете человеческий язык для построчного представления структуры программирования с помощью выражений, таких if blah then add 1 to xкак альтернатива nassi-schneiderman или блок-схемам. Это то, что подразумевается под грамотным программированием?
Джеймс П.
Вы единственный на этой странице, кто упомянул грамотное программирование Кнута - заставляет меня задуматься, под каким рок остальные плакаты жили последние сорок лет ...
cji
@James: купите копию «Tex - программы» Кнута и прочитайте ее. Это грамотное программирование.
Чи
10

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

Морган Херлокер
источник
10

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

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

Майк Данлавей
источник
3
Я думаю, что это лучший ответ здесь. Я не понимаю всего нежелания дать ему попытку, я имею в виду, что вам заплатят, чтобы сидеть и объяснять свой код! Черт возьми, если ваш код не является полным дерьмом, вам, вероятно, понравится, и независимо от того, насколько он хорош, вы, вероятно, найдете некоторые ошибки и места для улучшения.
Билл К
1
У меня был учитель, который объяснял вещи, печатая код, отображаемый через проектор. Возможно, это можно сделать как урок вождения. Если вы не можете, по крайней мере, пройти через весь код, вы можете лучше понять, что и как делается.
Джеймс П.
1
Я сам пытаюсь заняться преподавательской деятельностью, и я дал аналогичный ответ. Я с @Bill, я серьезно разочарован тем, что люди будут принимать такую ​​затворническую позицию. Неужели мы облажались за то, что верили, что стоит потратить время на объяснение хотя бы небольшой части кода?
Рей Миясака
1
@Rei: Отношения, плохие или хорошие, имеют тенденцию брать на себя большие подмножества в других отношениях похожих людей. У меня был обширный опыт (инженер, аспирант, профессор, консультант, долгосрочный сотрудник), поэтому мне нравится думать, что это дает перспективу. Кроме того, мои отношения изменились за эти годы.
Майк Данлавей
10

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

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

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

введите описание изображения здесь

Cos Callis
источник
Почему бы не сделать это и не взять деньги? Вы так уверены, что единственное, что вам нравится, - это создавать код, похожий на обезьяну?
Билл К
9

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

Джеймс
источник
18
На самом деле, это многое говорит мне об этом человеке ...
Марьян Венема
5
Это то, что «мало о чем говорит» означает в этом контексте - это действительно говорит о многом, но это просто не говорит о хорошем для человека.
Джозеф Вайсман
8

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

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

moonflash
источник
Я пытался использовать Cucumber в своем магазине некоторое время ... к сожалению (или, возможно, к счастью!) Моему боссу все равно, что происходит за кулисами, пока он работает. Просто заставить его понять преимущества написания тестов сначала было нелегкой битвой.
Джейсон Льюис
6

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

back2dos
источник
6

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

HLGEM
источник
6

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

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

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

Джон Тоблер
источник
1
Анализ затрат и выгод должен сделать эту работу. Возможно, у менеджера есть какие-то дополнительные преимущества. Если он не окупается, его трудно принуждать и защищать перед высшим руководством.
mbx
6

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

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

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

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

Рей Миясака
источник
+1 - я думал в том же духе - возьми его по просьбе - он, скорее всего, надоест и / или испугается до смерти слишком долго ...
Вектор
+1 Мне это нравится - «работает лучше, чем истирание».
Майк Данлавей
6

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

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

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

Инго
источник
Я собирался сделать то же самое предложение. Босс не хочет концептуального обзора, он хочет его построчно, так что должна быть возможность что-то выяснить за день или около того, что создает совершенно бесполезную, но внешне правильную документацию. Не имело бы значения, если бы это было крысиное гнездо if-elses в perl, которое было бы легко спутать с угловыми случаями, оно просто идентифицировало бы объявления переменных, модификации переменных, вызовы методов и т. Д. (Помните, что это строка за строкой, способ groks код).
PhilDin
Да, этот босс просто невежественен. Он не знает, что такое «абстракция», он не знает, что английский не подходит для выражения компьютерных программ, он не может представить, что он действительно не хочет знать все эти детали, поэтому он платит программисту. Поэтому он заслуживает такого урока.
Инго
5

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

Tough.

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

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

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

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

Нет.

Гонки легкости на орбите
источник
4

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

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

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

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

Том Ау
источник
3
Документирование построчно! = Продажа проекта. Уже должен быть документ, который предоставляет эту информацию, он называется требованиями. Я согласен с вашим описанием 2 рабочих мест, но документирование до этого уровня не будет выгодно для продажи проекта / системы / приложения. Существует соответствующий уровень документации для представления вашей работы, и это не так.
cdkMoose
Держу пари, что человек, выписывающий чеки в этой компании, не был бы рад, что этот менеджер тратил столько ресурсов компании.
JeffO
@ Джефф О: Может быть. Или это может быть то, что вся компания такая, вплоть до вершины.
Том Ау
4

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

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

Inoryy
источник
Это может быть самым конструктивным предложением на данный момент. Разработка, основанная на поведении, предназначена для удовлетворения именно этой потребности: помочь программистам и их менеджерам / клиентам договориться о том, что делает программное обеспечение. Написание описаний помогает при планировании кода, а выполнение тестов доказывает, что они все еще являются точными описаниями.
Натан Лонг
4

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

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

Peter Mortensen
источник
3

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

btown
источник
Это один из самых полезных ответов, которые я видел на этот вопрос. Я действительно пытался использовать docco, но обнаружил, что у него были проблемы с некоторыми из моих существующих комментариев, и он отображался неправильно. Поэтому я пошел с JSDoc и следовал инструкциям Google для создания документации. Не такой красивый, но очень полный, а также стандартный формат. Проблема с docco для меня в том, что вам нужно структурировать свой код так, чтобы он соответствовал комментариям, иначе это не имеет смысла. Спасибо за предложение.
Билли Мун
3

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

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

ddyer
источник
3

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

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

Питер Мунс
источник
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

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

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

tylerl
источник
1

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

Джон К.
источник
2
Вы имеете в виду менеджера или программиста?
Натан Лонг
Сколько компаний может позволить себе, чтобы каждый нетехнический менеджер использовал это время разработчиков?
JeffO