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

Question

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

Answer 1

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

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

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

Answer 2

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

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

Тесты, как правило, обновляются больше, чем комментарии. Я часто игнорирую комментарии из-за простого факта, что они очень быстро устаревают.

Answer 3

Этот вопрос является субъективным, и его следует избегать в StackOverflow согласно FAQ

Какие вопросы я не должен спросите здесь?

Старайтесь не задавать вопросы, которые субъективный , аргументированный или требующий расширенное обсуждение. Это место на вопросы, на которые можно ответить!

Короткий ответ будет:

• Избегайте чрезмерного комментирования:

  // add one to the count:
  i++;
  

• Используйте правильные имена переменных и методов:

  int x = i + j;
  int runSum = prevSum += newValue;
  

• Используйте стенографию кодирования, где доступно:

  if (x == y)
  {
    z = a;
  }
  else
  {
    z = b;
  }
  z = (x == y) ? a : b;
  

Answer 4

Купить и прочитать Код завершен 2 . Там есть масса вещей о написании легко читаемого / поддерживаемого кода.

Answer 5

Делайте код красивым, понятным и простым. Не комментируйте то, что вы делаете, когда это очевидно (например, я знаю, что такое foreach или если да, мне обычно не нужно объяснение).

Уловки кода (например, авто-свойства), которые заставляют простые вещи занимать меньше строк, тоже хороши.

Answer 6

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

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

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

Кент Бек придерживается трех принципов: коммуникация, простота и гибкость. Конечно, иногда вам придется поменять простоту на гибкость и наоборот.

Это может продолжаться и продолжаться. Ответ на этот вопрос помещается в большую книгу. Как предложил @rmbarnes, купите и прочитайте Code Complete 2. Я также предлагаю Шаблоны реализации Кента Бека - это очень связано с вашим вопросом.

Answer 7

Мои правила:

1. Дайте всему осмысленное имя и назовите его таким, какое оно есть. Избегайте использования «x» и «y» для переменных.
2. Не сокращайте НИЧЕГО. Мне все равно, как долго имя переменной, не сокращать, даже с комментариями. Интерпретация сокращений субъективна. Cmp означает компьютер? Компьютер? Компания? Комплимент? Сделайте это строгим правилом, без исключений, и им легко следовать.
3. Не помещайте несколько операторов в одну строку. Каждая строка выполняет одно действие.
4. Избегайте венгерских обозначений, таких как чума. Или это не венгерский?
5. Используйте скобки даже для однострочных (если, для) подструктур. Различия в отступах слишком легко потерять.

Answer 8

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

• Чтение кода: перспектива с открытым исходным кодом
• Качество кода: перспектива с открытым исходным кодом

Answer 9

1. Документируйте код, почему он делает то, что делает.
2. Убедитесь, что все функции переменных и т. Д. Названы последовательно и описательно
3. Используйте пробелы для группировки логических частей кода, чтобы он передавался при чтении.
4. Расположите функции / методы и т. Д. В логическом порядке.
5. (это моё личное предпочтение) Убедитесь, что код легко читается на экране без горизонтальной прокрутки (некоторые люди говорят также и вертикально, но, похоже, это меня не беспокоит).

Answer 10

Здесь много хороших ответов, я хотел бы добавить кое-что с точки зрения инженера, которому нравится большая картина. Я часто обнаруживал, что, получая обзор высокого уровня, с точки зрения диаграммы классов или обзора уровня пакета (диаграмма / комментарии и т. Д.), Черт возьми, если ничего не существует, 10 комментариев заголовка строки в файле, которые мне очень помогают. Мы можем использовать Doxygen / Javadocs для их генерации или потратить 10-15 минут, чтобы просто записать что-то в разделе комментариев.

Они не обязательно должны быть точными на 100%, и я сомневаюсь, что общая структура классов / пакетов изменится без полного переписывания.

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