Мій начальник хоче розповісти покрокове англійське пояснення нашого коду

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

Оскільки він не програміст, він не може слідувати коду, тому хоче, щоб це все було перекладено англійською.

Хтось раніше просив це зробити?

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

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

Це не розумний запит, чи не так?

ОНОВЛЕННЯ

Врешті-решт мені вдалося пояснити, чому не вдало використовувати час, щоб робити те, що він просить. Він розумний хлопець, і просто не розумів, що стосується моєї роботи. Одного разу він побачив цю посаду, я думаю, він швидко зрозумів, що це не звичайний запит.

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

Зрештою, всі партії залишилися задоволеними, і ми продовжили рух.

Ні , це не розумний запит!

Його відрадити ІТ , або хто - то інший його відговорити його, всіма засобами. Це ірраціональна ідея, яка хоч зробити це так дорого, але насправді цього ніколи не можна робити. Огляд функцій та підпрограм є розумним, але "пояснювати" кожен рядок коду - це не так. Для нього було б ефективніше навчитися читати мову в руці, ніж це робити.

Наступне, про що він буде просити, - це перекласти математичні формули чи інше в англійський текст. Хоча, безумовно, можливо, що відкривається багато можливостей для помилок та неправильних тлумачень , і цього ніколи не слід робити. Так само, як "переклад" коду на англійську мову.

Чи є у вас проектні документи ? Це англійське пояснення того, що робить код. Менеджеру, який не програмує, більше цього не потрібно.

Чи є премія мікро-менеджера року? Здається, що ваш начальник заслуговує на номінацію. Хтось, хто вважає, що йому потрібно розуміти код по черзі на рівні, але не хоче навчитися читати його безпосередньо, настільки ж ідеальний, як мікро-менеджер, як можна собі уявити.

Однією з переваг бути розробником є ​​те, що складність розуміння коду перешкоджає мікроуправлінню понад певну ступінь, принаймні на рівні детального впровадження, принаймні, нетехнічним управлінням, оскільки навіть найтвердіший мікро-менеджер визнає, що вони є над головою на тому рівні. Але геній вашого начальника може знайти спосіб зруйнувати кремнієву завісу.

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

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

З позитивного боку, можливо, ви можете отримати новий анти-шаблон, названий за вашою ситуацією? Як щодо анти-шаблону "Брудний угорський розмовник" після скандалу Monty Python, де тютюнопалівець намагається спілкуватися з тим, хто не розмовляє англійською мовою, використовуючи угорську книгу розмов, яка має помилкові переклади?

Сядьте з ним і поговоріть через 10 рядків коду. Поясніть кожну деталь, поки ви обоє не погоджуєтесь, що він зрозуміє її в тій мірі, в якій він хотів.

Можливо, цей досвід все, що він шукає: лише враження про те, як виглядає ваша робота, і як програмне забезпечення виглядає з вашої точки зору. Це гарна річ у моїй книзі.

Якщо після цього він все ще хоче, щоб ви продовжували, скажіть: зауважте, скільки запитань мені довелося задати; уявіть, якби мені довелося пояснювати все це, не маючи можливості задавати питання, як я, можливо, міг би знати, що включати і що не випускати? Скільки часу знадобиться, перш ніж результати будуть корисні для вас? Зараз скільки рядків ти хочеш, щоб я зробив таким чином?

Я не думаю, що це розумний запит. ДЖЕРЕЛ КОД не призначений для читання англійською мовою (або будь-якою іншою мовою з цього приводу).

Можливо, він боїться, що ти збираєшся змусити свій код зробити те, чого він не схвалює або знає. Якщо це так, я не думаю, що ви можете щось з цим зробити. Вам доведеться написати документацію або, можливо, переконати його / її найняти когось для аудиту вашого коду.

Це дійсно дуже просто:

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

Я мав подібний досвід до цього в попередній роботі. Мій менеджер був бухгалтером (і, таким чином, орієнтований на деталі з низьким рівнем), і не розумів або по-справжньому довіряв програмуванню. Вона не могла зрозуміти, що вона, як людина, яка не є технічною, не повинна сподіватися, що вона зможе зрозуміти деталі написаного мною. Після багатьох запитів надмірної документації та запитів навчити користувачів, які не є технічними, як керувати та змінювати код (так, насправді), я перестав намагатися схилити її, і відверто відмовився. Аналогія, яку я використовував для пояснення, була проста:

• Я не бухгалтер
• Я не повинен сподіватися, що я зрозумію кожну окрему транзакцію чи допис у наших облікових записах
• Це не означає, що облікові записи неправильні чи недостовірні, просто тому, що я їх не розумію
• Це стає можливим, довіряючи людині, яка їх склала

Зрештою, це мені так звучить: менеджер, якому важко довіряти своїм працівникам; або побоюється, що вони поїдуть, і вважає, що це ефективний спосіб пом'якшити її.

Єдине рішення цього - сісти і пояснити, чому це не має сенсу. Це ваша робота , щоб зрозуміти код і зробити можливим для кого - то з подібним набором навичок , щоб ваші , щоб зрозуміти це, не ваш менеджер. Показати їм цю нитку може бути хорошою ідеєю (або дійсно, дуже жахливо, залежно від їх особистості).

Рядок за рядком, це смішно. Що я можу запропонувати, це запропонувати створити документи з коментарів і дати йому це. Цього було достатньо для ряду грантів та аудитів уряду Канади, над якими я працював у минулому.

Він не отримає по черзі, але отримає метод за методом, який все-таки повинен бути більш детальним, ніж йому потрібно.

Деякі існуючі рішення, залежно від вашої платформи:

• C #: піщаний пісок
• Java: javadoc
• "C ++, C, Java, Objective-C, Python, IDL (аромати Corba та Microsoft), Fortran, VHDL, PHP, C # і певною мірою D." : доксиген

Йому було б набагато швидше навчитися читати код, ніж було б перекласти весь код будь-якої цікавої програми на англійську мову. Крім того, ми спробували це з COBOL, і це зовсім не допомогло. Якщо він не бажає вчитися, але просто хоче зробити своє незнання чужою проблемою, у вас є серйозно гострий бос.

Використовуйте свої технічні знання, щоб переслідувати свого начальника.

1. Дайте йому знати, що це займе стільки ж часу, як це зробили для вас, перш за все, кодувати це (Не соромтеся робити це довше.)
2. Запитайте його, яким сучасним він повинен бути цей документ. Повідомте його, що всі зміни кодування тепер займуть щонайменше вдвічі більше.
3. Якщо ви чи хтось інший знайде помилки, запитайте його, чи варто виправляти їх зараз, або чекайте, поки ви закінчите кодування psuedo. Нагадуйте йому про №1 та №2.

Як і всі погані пропозиції щодо вирішення проблеми, краще визначити проблему. Можливо, ваш начальник потрапляє у технічні питання з боку вищого керівництва, і він почуває себе ніяково, оскільки не може відповісти. Можливо, є один конкретний розділ коду, який він відчуває найбільше занепокоєний, тому ви можете обмежити це масштабне зобов'язання лише в цій галузі.

Подавши зразок, він може прийти до висновку, що якщо ви не розумієте, як працює кодування (Що таке цикл і що він робить для всіх цих елементів?), Це не має значення, на якій мові мова йде. Йому краще від розуміння програми з точки зору споживача енергії. Я думаю, що ви справедливо дасте йому знати, що ви краще пишете реальний код / ​​підказку - я шукаю іншу роботу.

Чому?

Постійний коментар не є розумним, але ось що я запитав: чому ви цього хочете?

Це тому, що ...

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

За цим проханням може бути розумне бажання, і ви, можливо, зможете зробити свого шефа щасливим, зрозумівши це та задовольнивши цю потребу.

Оновлення

На підставі Mikey'sкоментаря, можливо, я сказав це занадто прямо. Я не маю на увазі, що ви повинні буквально сказати "чому ви цього хочете?", А просто ви повинні це з'ясувати . Формулювання та тон голосу мають велике значення. Зокрема, ви можете сказати щось на зразок:

"Я думав над вашим запитом, щоб було пояснення кожного окремого рядка коду. Дещо так незвично робити такі речі. Мені було цікаво, чи, можливо, є щось, що я не повідомляю вам добре про свою роботу. Що ви насправді хочете зрозуміти щодо нашого коду чи про те, що я роблю? Що ви тут намагаєтеся зробити? "

Звичайно, можливо, що ваш начальник зовсім нерозумний. Але ймовірніше, що він не знає, наскільки чужий цей запит і має на увазі якусь раціональну мету.

Якщо ні, почніть полірувати своє резюме. :)

Здається, гарний шанс спробувати грамотне програмування. Google це. :)

Але ... це не обов'язково цілком необгрунтований запит. Частина вашої роботи (важливіша частина - imo) полягає в повідомленні свого алгоритму (-ів) іншим розробникам, а за потреби і нетехнічним особам. Думаю, самотні геніальні програмісти, які не вміють спілкуватися, завжди проблемні.

З цією метою ваш код повинен бути чітко чітким (тобто: справді самодокументований або добре документований; під «самодокументуванням» я маю на увазі, що змінні та функції мають одне значення або відповідальність, і їх назви чітко відображають). У вашого начальника можуть бути вагомі причини для його прохання. Можливо (я тут просто здогадуюсь) ви або ваш попередник маєте репутацію непроникного, крихкого коду, і це засіб вашого начальника. Це трохи екстремально, але може бути корисною для вас вправою. Я припускаю, що він знає, що потрібен час, щоб написати кращі документи (а якщо він цього не зробить, йому слід навчитись - це як написання курсової роботи: писати потрібно більше часу, ніж читати).

Навіть переклад рядка за рядком не буде ефективно передавати значення кожного рядка коду. Програмісти, які розуміють рядок коду, завжди знаходяться в контексті багатьох факторів. Потрапте в щось на зразок шматка з багатопотокових кодів і англійський переклад не матиме більше сенсу, ніж необроблений код. Подумайте про функціональність, яка розподіляється між кількома функціями / файлами. Деякий код абсолютно не має сенсу без пояснення великої кількості іншого коду. Спробуйте пояснити різні частини, які беруть участь у введенні залежності "рядок за рядком", і ви побачите, що я маю на увазі. Практично про все, що виходить за рамки функціонального коду, що відповідає функціям Бога, знадобиться велика кількість програмних знань, щоб зрозуміти переклад з англійської. Крім того, подивіться на щось таке просте, як твердження про рішення if / else. Немає рядка за рядком, оскільки наступний рядок залежить від даних про час виконання. Наступний рядок може бути однією з кількох можливостей.До того часу, як ви поясните, що робить ваша заявка, ви зробите свого прем’єр-міністра програмістом, і вам обом буде 5 років старше.

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

Він швидко дізнається, що отримує більше, ніж торгувався, що змусить мене сумувати, бо мені подобається пояснювати речі :-)

Якщо ви посилаєтесь на свого "боса", це "середній менеджер, який відповідає за вас / вашу команду"? або Власник вашої компанії? Ви платите "по годині" чи "по зарплаті"?

Якщо ваш начальник - менеджер середнього рівня, який підзвітний, ОБРАЗУЙТЕ СВОЄМО БОСУ, зауважте, що для виконання вимог вашого начальника ваша продуктивність для компанії знизиться на 1/3 тієї, що вона може бути.

ЯКЩО ваш начальник - "хлопець, який підписує чеки", поясніть йому те саме, тільки більш дипломатично. Ваше завдання перейшло від «Написати код» до «Напишіть код, напишіть пояснення коду, поясніть пояснення».

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

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

і змусити свого боса написати в майбутньому тест BDD.

Він не повинен турбуватися про те, щоб знати щось із цього. Скажіть йому, що в реалізації розробки програмного забезпечення можуть змінюватися зміни. Дизайн подій може бути змінений. Розкажіть йому про приховування, капсулювання та абстрагування інформації.
Він, як частина вашої команди, як клієнт вашого коду, в більш широкому розумінні, повинен працювати лише з чіткою абстракцією високого рівня того, що робить ваш код. Так само, як будь-який шар вашого коду працює з іншим шаром чужого коду. Знаючи більше, ніж це, це лише сповільнить його і ризикує зробити його припущення, виходячи з внутрішнього опрацювання вашого коду. Ці припущення припиняться, коли вам доведеться змінити код, що стане проблемою, якщо він побудував на їх основі будь-яку систему чи процес.
А також виконання подібних робіт знизить вашу ефективність. Не тільки вам доведеться вносити наступні зміни у двох різних місцях, але це також негативно вплине на ваш моральний стан праці, що ще більше зменшить ваш результат.

Краса англійської полягає в тому, що красиво заперечує. Якщо ви користуєтеся цим у своїх інтересах, ви більше ніколи не зможете повторити цей запит. Я б взяв невеликий фрагмент коду як зразок, але той, який є дуже резюменим і зовсім не зрозумілим. Тоді я б написав коментарі технічною англійською мовою так, ніби ви пишете це для глави книги програмування. Чим довше і складніше слідкувати, тим краще. Скажи йому, скільки годин знадобилось тобі, щоб задокументувати цю одну особливість. Потім поясніть, що це лише 1/10 від 1% (використовуйте фактичні цифри на основі рядків коду, якщо можете, вони, ймовірно, гірші за це) фактичної бази коду. Коли він зрозуміє, що не має поняття, що говорить переклад з англійської, і що для цього рівня документації знадобиться 20 000 людино-годин, він відступить досить швидко. Але дуже щиро намагайтеся виконати його завдання. Не намагайтеся це робити, якщо ви не можете це зняти, і він підозрює, що ви граєте в нього.

Це схоже на кандидата на спеціальне свято- смугастий бос Ділберт- смуга! Його прохання , звичайно , НЕ звучить розумно на перший погляд.

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

Щодо себе, порахуйте години, які знадобляться для його, здавалося б, химерного запиту, а потім визначте, чи не краще вам вкладати частину такої кількості часу в пошук нової роботи, працюючи для роботодавця, який бажає поводитися з вами. як професіонал!

Принесіть його до вашого офісу та огляньте його код.

Він зрозуміє частково через те, що висунув безглузді вимоги, і піде геть і ніколи більше не турбує тебе.

Якщо ви не вкажете на його вимоги допомогти йому зрозуміти ваш код, він знайде різні, але настільки ж абсурдні способи кинутись на вас.

Це випадок, коли умиротворення працює краще, ніж стирання.

Було б дуже приємно, якби у нас був перекладач "Мова X на англійську", який це робить. Тоді можна було б посміхнутися і сказати: жодних проблем, шефе, це вам доведеться за хвилину. А потім приходить пошта з мегабайтими тексту, який читає:

• Нехай a - це новий цілий масив з 20 елементами.
• Нехай x - змінна для зберігання цілих чисел.
• Встановіть x на 0
• Хоча х менше 20, зробіть те, що прописано в наступних 2 рядках
• встановіть елемент масиву a з індексом x на результат виклику nThPrime з аргументом x + 1
• збільшити х на 1
• ….

Іншим варіантом було б запропонувати програмування Шекспіра відтепер.

Мій начальник хоче розповісти покрокове англійське пояснення нашого коду

Жорсткий.

Оскільки він не програміст, він не може слідувати коду, тому хоче, щоб це все було перекладено англійською мовою.

Якщо він не програміст, він не повинен читати код. Зовсім.

Натомість надайте документацію високого рівня.

Це не розумний запит, чи не так?

Немає.

Як програміст, у вас справді є "дві" роботи.

Перший - створити хороші програми. Друга - "продати" їх клієнтам всередині і за межами компанії.

Прохання вашого начальника "шкодить" вашій першій роботі. Для документування програм потрібно більше часу. З іншого боку, він насправді змушує вас працювати більше на своїй "другій" роботі.

Ваш начальник просить задокументувати свою програму англійською мовою на користь ЇЇ, і, мабуть, на користь людей, з якими йому доводиться мати справу, всередині та поза компанією. Якщо ви допомагаєте йому виконувати свою роботу, це може працювати на вашу користь у довгостроковій перспективі, коли ви попросите у нього більше обладнання, персоналу або грошей на підвищення. Зрештою, він попросив вас зробити більше роботи.

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

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

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

PS Жартую, він ідіот.

Хоча я погоджуюся, що це необгрунтований запит, ваш начальник може оцінити щось на кшталт виходу Docco , який розділяє ваш код і коментарі по рядку або за застереженням на два колонки, з кодом на одному стороні та прозі з іншого. Ви, звичайно, повинні самі вводити коментарі, але презентація IMHO дуже приємна, навіть для нетехнічних читачів. Дивіться, наприклад, рядок коментованого розділу кодованого коду для 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

Проблема тут полягає в тому, що, хоча коментарі пояснюють, що робить кожен рядок, ви все ще не маєте уявлення про те, що насправді робить код, якщо ви не розумієте, які всі наслідки. Це очевидно, якщо ви програміст і раніше бачили цю схему; але покажіть це тому, хто розуміє лише продажі, і він буде так само розгублений, прочитавши коментарі, як і раніше.

Ви могли фактично заощадити час , навчивши свого начальника деякому базовому програмуванню. Якщо він хоче прочитати ваш код, дайте йому інструменти, щоб мати змогу це зробити. Більшість мов мають досить компактний синтаксис, а вивчення структури займає лише годину чи дві. Він, майже напевно, здасться через кілька днів, але принаймні він буде знати, що він передає, і ще важливіше, чому він не хоче читати ваш код.

ІМХО ... якщо він відповідає за виконання завдання, він повинен знати, як це працює ... :)