Улучшение [закрытой] удобочитаемости кода

Question

Улучшение [закрытой] удобочитаемости кода

Используя аннотацию @WebFilter, это можно сделать следующим образом:

@WebFilter(urlPatterns = {"/*" })
public class AuthenticationFilter implements Filter{

    private static Logger logger = Logger.getLogger(AuthenticationFilter.class);

    @Override
    public void destroy() {
        // TODO Auto-generated method stub

    }

    @Override
    public void doFilter(ServletRequest arg0, ServletResponse response, FilterChain chain)
            throws IOException, ServletException {

         logger.info("checking client id in filter");
        HttpServletRequest request = (HttpServletRequest) arg0;
        String clientId = request.getHeader("clientId");
        if (StringUtils.isNotEmpty(clientId)) {
            chain.doFilter(request, response);
        } else {
            logger.error("client id missing.");
        }
    }

    @Override
    public void init(FilterConfig arg0) throws ServletException {
        // TODO Auto-generated method stub

    }

}

24

readability documentation language-agnostic

задан Peter 19 April 2009 в 14:33

10 ответов

Последовательный стиль форматирования
Хорошее использование пробела
Используя короткие, но понятные имена
Не слишком много комментариев (как Вы упоминаете), но когда я делаю, комментируют whys кода, и если применимо, , почему nots (то, почему некоторый другой implemention не использовался, особенно если это походит на него, должно быть очевидно сделать так).
не оптимизируют код, пока профилировщик не говорит мне его медленное или неэффективное

8

ответ дан Patrick Cuff 16 October 2019 в 08:14

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

8

ответ дан tvanfosson 16 October 2019 в 08:14

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

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

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

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

5

ответ дан TomHastjarjanto 16 October 2019 в 08:14

Самодокументирование кода:

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

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

4

ответ дан Assaf Lavie 16 October 2019 в 08:14

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

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

Людям, которые используют классы и методы, записанные Вами, не придется прочитать Ваш код, чтобы понять, как использовать их. Таким образом, я думаю, что нужно зарегистрировать то, что легальные входные и выходные диапазоны, а также важные инварианты. Например, функция берет указатель в качестве аргумента. Неважно, как хорошо Вы называете свою функцию, никогда не может быть очевидно, допустимо ли предоставление ПУСТОГО УКАЗАТЕЛЯ или является ли ПУСТОЙ УКАЗАТЕЛЬ допустимым возвращенным результатом. Часто-1 и 0 используются для передачи сигналов о некоторых что-то как объект, разыскиваемый не найденный или подобный. Это должно быть зарегистрировано.

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

4

ответ дан Erik Engheim 16 October 2019 в 08:14

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

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

2

ответ дан Leonidas 16 October 2019 в 08:14

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

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

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

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

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

1

ответ дан Drew Noakes 16 October 2019 в 08:14

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

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

0

ответ дан paperhorse 16 October 2019 в 08:14

Откажитесь от кодового мусора.

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

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

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

1

ответ дан 28 November 2019 в 22:45

Другие вопросы по тегам:

readability documentation language-agnostic

Похожие вопросы:

score 28 · Accepted Answer

Проверьте Jeff Atwood Запахи Кода сообщение в блоге. Это в значительной степени подводит итог его. Я добавлю свой персональный идеал когда дело доходит до хорошего читаемого кода:

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