Улучшение удобочитаемости кода

Ответ 1

Отъезд Jeff Atwood Код запаха в блоге. Это в значительной степени подводит итог. Я добавлю свой персонаж, когда дело доходит до хорошего читаемого кода:

• Согласованность: это относится к форматированию, использованию фигурных скобок, именованию (переменным, классам, методам) и макете макета (если вы похоронили исходный каталог где-то под /css, я прихожу после вас с мачете);
• Размер:, если функция не подходит целиком на экране в обычной среде IDE при нормальном размере шрифта, тогда вам нужна довольно хорошая причина, почему бы и нет. Конечно, есть несколько действительных случаев для гораздо более длинных функций, но они значительно перевешиваются вопиющими примерами. Разложите, если необходимо, чтобы ваши функции были простыми;
• Замечание:. Некоторые программисты склонны использовать комментарии в качестве замены читаемого кода или просто комментировать ради комментариев (например, /* finished */ комментарии перед return true;). Серьезно, какой смысл? Самый (хороший) код объясняет сам себя;
• Никогда не вырезать и вставлять в рамках проекта: вполне приемлемо взять фрагмент кода из одного проекта в другой (каждый проект - остров), но вы должны никогда нетривиальный сегмент кода из одного проекта в какую-то другую точку проекта. Неизбежно один изменяется, и вы оставляете некоторого плохого разработчика с задачей взглянуть на эти два или более сегментов кода, пытаясь понять, как (и, возможно, более важно, почему) они разные; и
• Избегайте повторного кода:, если вы снова и снова повторяете одну и ту же последовательность утверждений (или очень похожих), абстрактно или параметризуете ее. Если вы видите очень похожие заявления, то тенденция состоит в том, чтобы сбрасывать их, полагая, что они все одинаковые (когда обычно они не будут иметь никакого отношения к делу).

Ответ 2

• Совместимый стиль форматирования
• Хорошее использование пробелов
• Использование коротких, но значимых имен
• Не так много комментариев (как вы упоминаете), но когда я это делаю, прокомментируйте whys кода и, если применимо, почему nots (почему wasn ' t используется какая-то другая реализация, особенно если кажется, что это должно быть очевидно).
• Не оптимизируйте код до тех пор, пока профайлер не скажет мне, что он медленный или неэффективный

Ответ 3

Используйте хорошие имена переменных и методов. Разбить код на значимые части, которые выполняют конкретные цели. Держите свои классы сплоченными (все работает вместе) и развязаны (между классами существует несколько зависимостей). Не повторяйте себя (СУХОЙ). Следуйте за дядей Бобом СОЛИДНЫЕ принципы (а не законы, так как он указывает) в той степени, в которой они работают, чтобы сделать код лучше.

Ответ 4

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

Некоторые важные моменты:

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

В книге есть еще несколько небольших правил, я действительно рекомендую ее. Также получите Code Complete 2.

Ответ 5

Самодокументирующий код:

• Хорошие соглашения об именах
• Четкий дизайн и разделение ответственности между компонентами (класс, функция и т.д.).

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

Ответ 6

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

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

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

Кроме того, я думаю, что ключом к документированию кода является не документирование того, что такое класс или метод , или, но что за ним стоит .

Ответ 7

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

В Visual Studio можно выбрать и исправить этот стиль. Это помогает всем остальным в вашей команде читать один и тот же код. Это также упрощает отслеживание истории в системе управления версиями, когда вам не нужно различать "пустые" изменения (изменение стиля) и реальные изменения.

Ответ 8

Придерживайтесь парадигмы, используемой в среде, которую вы кодируете.

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

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

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

Консистенция - это ценная характеристика, которая снижает когнитивную нагрузку для потребителя-потребителя кода.

Ответ 9

Сохранить код.

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

Я думаю, что такое же мышление, применяемое к коду, приносит нам гораздо более чистый код. Примеры включают в себя /* getFoo() gets the foo */ -стильные комментарии, ненужные круглые скобки и фигурные скобки, чрезмерно определенные имена переменных и венгерские нотные бородавки.

Что представляет собой чарджукк, зависит от команды, окружающей среды и проекта - некоторые люди любят бородавки; в некоторых средах рендеринг кода осуществляется таким образом, что некоторые полезные утилиты полезны (например, комментарии к комментариям и // end for); некоторые проекты требуют более обширного комментирования для соответствия стандартам или для всестороннего документирования API. Но когда команда установила стандарты того, что означает графический объект для своих проектов, многие решения становятся проще, а его код становится более последовательным и читабельным.

Ответ 10

Все ответы (и вопрос) основаны на предположении, что читаемость несет ответственность только писателя кода. Если вы действительно не хотите читать код, и у вас есть список сдающихся чтений (код пахнет), который соответствует 99% доступного кода, и вы действительно не хотите даже очень много думать о том, что делает какой-то код, то вы не найдете код, читаемый.

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