Прокомментировать интерфейс, реализацию или обоих?
Используя java-8, вы можете фильтровать список, результатом будет List<HomeScreenChatsHelper>, который имеет HomeScreenChatsHelper с тем же id
List<HomeScreenChatsHelper> mChats = new ArrayList<>();
//filter
List<HomeScreenChatsHelper> result = mChats.stream()
.filter(str->!str.getId().equals(Id)).
.collect(Collectors.toList());
Или с помощью Iterator
// Iterator.remove()
Iterator itr = mChats.iterator();
while (itr.hasNext())
{
HomeScreenChatsHelper x = itr.next();
if (x.getId().equals(Id)) }
itr.remove();
}
}
6 ответов
Как правило, я использую тот же принцип СУХОГО (не повторяй себя), что и с кодом:
- на интерфейсе, документирование интерфейса
- на реализации, документирование особенностей реализации
специфических для Java : при документировании реализации используйте тег {@inheritDoc} для «включения» javadocs из интерфейса.
Для дополнительная информация:
- Официальная документация Javadoc
- Неофициальный совет .
Если вы используете надстройку GhostDoc , она обновляет реализацию с комментарием из интерфейса, когда Вы щелкаете правой кнопкой мыши и выбираете «Document This» в методе.
Для C # это зависит от IMO: если вы используете явные реализации интерфейса, то я не буду документировать реализацию.
Однако, если вы реализуете интерфейс напрямую и выставляете члены интерфейса с вашим объектом, тогда эти методы должны быть тоже задокументировано.
Как сказал Нат, вы можете использовать GhostDoc для автоматической вставки документации интерфейса в реализацию. Я сопоставил документ этой командой с сочетанием клавиш Ctrl + Shift + D и одним из клавиш, которые я почти автоматически нажимаю. Я считаю, что ReSharper также имеет возможность вставить документацию интерфейса, когда он реализует методы для вас.
Мы просто комментируем интерфейс, комментарии так просто не синхронизируются ни с производным, ни с базовым классом / интерфейсом это приятно иметь его в одном месте.
Хотя, похоже, @Nath может предложить автоматизированный инструмент для документирования, который поможет сохранить все вместе (звучит круто, если вы используете это). Здесь, в WhereIWorkAndYouDontCare, комментарии относятся к dev, поэтому предпочтительным является одно место в коде
Только интерфейс. Комментирование обоих - это дублирование, и, вероятно, два набора комментариев со временем будут не синхронизированы, если код изменится. Прокомментируйте реализацию с помощью "Implements MyInterface" ... Такие вещи, как Doxygen, будут генерировать документы, которые в любом случае будут включать производные документы в документы для реализации (если вы их правильно настроили).
Для комментирования интерфейса должно быть достаточно документации, чтобы понять, как использовать реальную реализацию. Единственный раз, когда я бы добавил комментарии к реализации, это если бы у нее были частные функции, которые были вставлены для удовлетворения интерфейса, однако они были бы только внутренними комментариями и не были бы замечены в документации онлайн или доступны для клиентов.
Реализации просто, если они соответствуют интерфейсу, нет необходимости документировать их отдельно.