Как я делаю свой код легче для следующего разработчика, который поймет? [закрытый]

Все думают, что чужой код - отстой. И вы должны думать, что ваш код тоже отстой. Почему? Потому что это так. Это действительно так.

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

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

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

Эта конкретная конструкция является общей, и «i» здесь подходит.

Что касается другого примера, он субъективен, и до тех пор, пока вы последовательны в своих соглашениях, все будет в порядке.

В основном: БУДЬТЕ ПОСТОЯННЫМ

РЕДАКТИРОВАТЬ: Что касается справки, вот тот, который вы можете использовать:

Ссылка на соглашение об именах кодов

Помимо точки «фактическая работа» (- предыдущие 3 ответа довольно хороши -) имейте в виду, что мы (программисты) - высокомерная (и в значительной степени невежественная) группа чудаков;

Неважно как сильно вы пытаетесь написать хороший (и хорошо документированный) код или сколько синтаксического сахара вы бы применили: для новичка ваш код всегда будет "отстой" (по крайней мере, до определенной степени), поскольку он не писал.

В вашем примере (с использованием цикла i for) это всего лишь переменная локального цикла. Я бы не был слишком строг к себе. Пока код в значительной степени объясняется самим собой, ему просто нужно управлять.

Для переменных, которые вы используете для итерации, обычно используются имена «i» или «x». Это не вызовет у большинства людей - если кого-то и обнаружит, значит, они, вероятно, не видели достаточно реального кода, чтобы выполнять вашу работу. :)

Если вы действительно беспокоитесь о том, что кто-то думает о вашем коде, то попытка называть вещи последовательно может быть неплохой идеей. С другой стороны, не идите и не рискуйте сломать все просто из-за некоторой одержимости заставить других людей любить ваши имена переменных, потому что кто-то будет их ненавидеть, что бы вы ни делали. Если это работает, и это хорошо задокументировано, и ваши имена переменных что-то означают (помимо переменных 'i' и 'x', упомянутых выше), то это "достаточно хорошо" IMO.

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

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

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

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

Конкретный ответ на ваш вопрос, нет необходимости переименовывать простые переменные счетчика, такие как i. По факту,i и x обычно используются в этой ситуации в большинстве языков c, поэтому любой, кто знаком с этими языками, будет очень комфортно. Другие переменные, особенно переменные-члены класса и используемые в методах, действительно требуют приличных (хотя и не слишком длинных) имен.

Среди переменных i считается особым случаем именования. Наряду с j , k и l , i хорошо понимается как временная переменная «счетчика» для использования в циклах. Пока вы используете его последовательно, это не будет проблемой.

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

• Будьте последовательны : Убедитесь, что ваши соглашения об именах переменных и дизайн согласованы. Если вы часто создаете временные переменные для циклов, всегда ли они называются i ? Вы используете i где-нибудь еще для обозначения чего-то другого? Согласованность означает, что в вашем коде есть шаблоны логики. Шаблоны легко подбирать и следовать им.
• Объясните себя : Убедитесь, что комментарии объясняют , почему вы что-то делаете, а не то, что вы делаете. Комментарии вроде // Цикл по массиву не помогают; любой может прочитать ваш код и увидеть, что вы выполняете цикл. Они хотят знать, почему вы это делаете.
• Задокументируйте свои классы : Предоставление кому-либо документации о назначении каждого класса, интерфейса, члена, свойства, даже если это всего лишь объяснение в одну строку, является огромным подспорьем при попытке понять, что делают компоненты приложения. . Если вы включите комментарии XML в Visual Studio, он будет генерировать предупреждение каждый раз, когда вы забудете добавить минимум сводки для каждого члена. Эти комментарии также имеют дополнительный бонус в виде поддержки intellisense, что делает работу с кодом еще проще.

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

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

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

Если вы сделали следующее, это значительно облегчит вашу проблему:

1. Создайте архитектурный документ, показывающий общую структура вашего программного обеспечения и какие части взаимодействуют.
2. Задокументируйте каждую переменную / функцию / класс-член, чтобы указать, что они делают (а не то, как они это делают).
3. Напишите и задокументируйте некоторые тесты, которые показывают, как работает ваша программа, и что вы ожидаете от нее в ожидаемых вами сценариях использования. Убедитесь, что все данные примера записаны, чтобы ваш заменяющий мог повторно запустить тесты, чтобы понять, как должны работать.
4. Убедитесь, что ваш код соответствует стандарту.Даже если он нестандартный, код, который, по крайней мере, согласуется с самим собой, будет легче отслеживать.
5. Если вас это устраивает, оставьте некоторые контактные данные, чтобы парень или девушка, взявшие на себя ответственность, могли хотя бы написать вам по электронной почте или позвонить, если они действительно застряли. Я делал это для различных проектов / работ. На этот странный вопрос не уйдет много времени, но он может легко спасти душу, унаследовавшую вашу кодовую базу.

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

Нет, это не общие стандарты.

Проекты (или компании) обычно устанавливают для себя рекомендации по стилю кодирования. Однако последовательность, вероятно, является правилом, которому следует любое руководство по стилю.

Я считаю, что ii намного превосходит i в качестве основного счетчика циклов. Я не помню для конечно, но я считаю, что научился этой технике от Code Co полный. Почему лучше? Попробуйте поискать i в своем источнике. Затем попробуйте поискать ii. Посмотрите, что работает лучше.

Я видел, как кто-то использовал Index, Indexx, Indexxx и т. Д. В качестве счетчиков. Сейчас он работает в McDonalds.

Короче: я бы предпочел i, j, k.

Вот хорошая статья, которая должна вам помочь:

http://msdn.microsoft.com/en-us/library/xzf533w0 (v = VS.71) .aspx

Вы также можете потратить немного времени и познакомиться со своей командой « Refactor », прежде чем новичок увидит все ваши bool aintSo = false; язык во всем творении.

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

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

И ваши приложения находятся в системе контроля версий ... Верно?

Обычно наименее полезной является переменная (например, счетчик), чем короче ее имя. «i» вполне стандартно, так что не беспокойтесь об этом. Однако важные переменные, а также переменные с длительным сроком службы должны иметь описательные имена.

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

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

И, наконец, прокомментируйте хаки, а не очевидное :)

Хорошо, я собираюсь пойти против.

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

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

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

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

Иногда, перебирая массив «blah», уместно называть его «blahIndex». Это особенно верно, когда более одного индекса используется более чем для одной структуры данных. Такой формат, как «blahIndex», напомнит уму, какой индекс соответствует какому элементу.

Тем не менее, в мире программирования принято считать, что переменная с именем «i» является индексом. Это означает, что сохранение «i» как есть никого не должно смущать.

Я могу сказать вам по опыту: другие не пишут красивый код . На самом деле, если ваш код каким-то образом документирован, он уже намного лучше среднего.

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

Нет никакой замены работе в команде, особенно в первые годы вашей карьеры.

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

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

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

Я буду откровенен, но имейте в виду, что необходимо также найти баланс.

Делайте то, за что вам платят. Особенно актуально для подрядчиков. Вы навязываете свой стиль другим? Соблюдайте стандарты кодирования и форматирования компании.

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

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

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