Должны ли вы написать хорошую документацию и чистый код для увеличения «Bus Factor»?

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

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

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

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

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

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

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

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

PS Ни мистер Грин, ни Макиавелли на самом деле не достигли многого, кроме написания книг, которые пытались льстить потенциальным «жестким людям» того времени. Примите их совет с зерном соли.

Если вы незаменимы, вы не можете быть повышены.

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

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

Кладбища полны незаменимых людей.
- Голль, Шарль Де

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

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

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

  int sendData (int targetModule, void * data, size_t byteCount);
  int recvData (int sourceModule, void * data, size_t maxBytes);

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

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

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

Быть заменяемыми, разве это не противоречит интересам разработчика?

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

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

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

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

Быть заменяемыми, разве это не противоречит интересам разработчика?

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

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

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

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

Я не знаю, что вы за человек, но это лучше отвечает моим интересам.

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

Быть заменяемыми, разве это не противоречит интересам разработчика?

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

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

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

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

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

Какой маршрут вы бы предпочли?

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

С другой стороны, возможность замены дает вам несколько бесценных преимуществ:

• возможность взять отпуск
• не быть на связи
• свобода уйти и работать над новым и интересным проектом

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

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

Превосходная документация в конечном итоге устареет с рефакторингом / эволюцией, и ее поддержание в актуальном состоянии отнимает много времени.

Чистый код + модульный тест> отличная документация

Ответ на ваш вопрос - «да». Да, вы должны написать хорошую документацию и чистый код. Умышленное поступление в противном случае демонстрирует отсутствие целостности, которая, хотя и становится все более распространенной в деловом мире, внезапно становится «хорошей» вещью.

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

Одной из основных целей компаний-разработчиков программного обеспечения является увеличение их Bus фактора

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

Закон 11 Научитесь держать людей зависимыми от вас.

Что это значит для вас?

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

Это ваш вызов.

(при условии производственного кода)

Я склонен идти немного дальше. Я писал о том, чтобы сделать программы «доказательством идиота», но я не всегда квалифицирую это: я пишу много кода, который другие люди не увидят или не будут работать (по крайней мере, это ожидание, когда оно написано). яя идиот, от которого я пытаюсь себя защитить в этом случае. Хорошо, когда ваша программа обнаруживает проблемы для вас, и проблема настолько упрощена, что становится очевидным, что существует ошибка и ее происхождение. Правда в том, что детали реализации очевидны, когда вы пишете программу (если вы не реализуете ее преждевременно), но они должны быть абстрагированными и устойчивыми к ошибкам для клиентов (даже если локальность модуля существует). Причина в том, что программы становятся очень сложными. Иногда вы можете разделить проблемы, но не все время. Если вы сохраняете свои компоненты очень строгими, простыми, хорошо инкапсулированными и защищенными от идиотов, они, как правило, хорошо масштабируются, и большинство дефектов обнаруживаются до их отправки. Это проще для повторного использования, и у вас больше уверенности и легче использовать программы. те сложные программы, которые вы пишете, становятся более сложными (даже для вас) через некоторое время вне программы. Когда вы прочитаете его за 6 месяцев, это может занять абсурдное количество времени, чтобы понять и отладить его по сравнению с версией для идиота. Если компонент вносит критическое изменение, в противном случае он может оставаться незамеченным в течение длительного времени. Программы сложны; вы не можете избежать этой реальности, но вы можете сделать это доказательством идиота, который сделает вашу жизнь намного легче, когда что-то пойдет не так, или когда это нужно будет использовать повторно или изменить. Следовательно, подход, защищающий от идиотов, означает, что ваше программное обеспечение может быть понято, использовано повторно или поддержано вашими юниорами или новичками в команде (а не просто кем-то таким хорошим / опытным, как вы). Замена - это отдельная задача: если людям нравится работать с вашими программами, вы делаете хорошую работу - не надо беспокоиться о замене. Конечно, я мог бы придумать сценарии, в которых непонятные программы могли бы спасти вашу работу, но написание хорошей программы, которую другие могут использовать и поддерживать, - явно меньшее зло (посмотрите на реакции других). Если я ловлю себя на том, что пишу что-то, что не является идиотским доказательством, я пытаюсь это исправить.

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

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

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

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

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

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

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

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

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

Если вы ДЕЙСТВИТЕЛЬНО хотите быть незаменимыми (что вы, возможно, захотите пересмотреть после прочтения всех ответов ...) - зачем останавливаться на том, чтобы не документировать код?

Есть действительно блестящее руководство о том, как писать не поддерживаемый код, который вы обязательно должны прочитать: http://thc.org/root/phun/unmaintain.html

Наслаждайтесь! (Я, безусловно, сделал ...)