Как упростить мой код для следующего разработчика?

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

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

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

Например, я всегда делал такие вещи.

for (int i = 0; i < blah.length; i++)
{
//Do stuff
}

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

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

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

Ответ 1

Code Complete от Steve McConnell - хорошее место, чтобы начать поиск ответов на ваши вопросы и многое другое, чего вы не спросили но скоро.

Ответ 2

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

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

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

Ответ 3

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

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

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

Ответ 4

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

Вот несколько хороших правил для упрощения понимания кода:

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

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

Ответ 5

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

Ответ 6

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

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

Ответ 7

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

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

В основном: ПОСМОТРЕТЬ

EDIT: для справки, вот что вы можете использовать:

Ссылка на кодовое название кода

Ответ 8

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

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

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

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

Ответ 9

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

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

И ваши приложения находятся в исходном управлении... Правильно?

Ответ 10

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

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

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

Ответ 11

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

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

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

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

Ответ 12

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

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

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

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

Ответ 13

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

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

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

Ответ 14

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

Ответ 15

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

Сократить вещи: лучше бы увидеть i, j, k.

Ответ 16

Нет, они не являются общими стандартами.

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

Ответ 17

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

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

Ответ 18

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

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

Ответ 19

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

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

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

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

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

Ответ 20

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

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

Тем не менее, это общепринятое соглашение в мире программирования, что переменная, называемая "i" , является индексом. Это означает, что сохранение "i" as-is не должно путать кого-либо.

Ответ 21

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

Ответ 22

Хорошо, я собираюсь быть противоположным здесь.

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

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

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