Как Вы избегаете дублирования в комментариях для документации? [закрытый]
Как заметил @Alec выше, то, что вы хотите, выглядит как функция zipWith :
list1 = [True, True, False]
list2 = [True, False, False]
list4 = zipWith (/=) list1 list2
Это даст вам [False, True, False] в ghci. Если вы хотите использовать map , то вы бы сделали что-то вроде этого:
list1 = [True, True, False]
list2 = [True, False, False]
list3 = zip list1 list2
list4 = map (\(x, y) -> x /= y) list3
10 ответов
Я стараюсь избегать дубликатов, описывая процесс также в кратком изложении. В параметры можно добавить такие детали, как допустимые диапазоны или то, как пользователь должен получать эту информацию. Для возвратов я также перечисляю любые условия ошибки, например:
/// <summary>
/// Gets a dto of personal info by querying the current list of users (or active directory or SQL)
/// </summary>
/// <param name="userId">
/// The id of the user. Must be greater than 0. The ID is stored in the application context or can be retrieved by a call to GetUserIdByName.
/// </param>
/// <returns>
/// A dto containing personal info. Returns null if the specified user information was not found.
/// </returns>
public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...}
Существует причина для применения этого стандарта, даже если вы считаете, что это иногда избыточная информация. (то есть «userId -> ID пользователя»). Этот комментарий также неявно содержит информацию о том, что никаких дополнительных ограничений на этот параметр НЕТ.
Итак,
...
///<param name="angle">
///The angle in degrees. Must be below 360 and above 0.
///</param>
...
Если вы не добавите это, «Должно быть ниже x». и выше y ", то вы заявляете, что нет никаких ограничений на параметр.
Аналогично для тега
Эта информация очень важна, и stylecop просто заставляет ее добавить.
"документирование методов, которые делают комментарии действительно полезными. Я считаю, что мои комментарии часто содержат много повторений только для того, чтобы удовлетворить требования StyleCop"
. Полезные и избыточные не имеют ничего общего друг с другом ,
Вы не определили «полезный» в своем вопросе. Обычно это означает «больше, чем требуется stylecop». Если вы чувствуете необходимость написать что-то большее, тогда напишите что-то большее. Stylecop - это минимум; вы можете выйти за пределы этих минимумов.
В вашем случае, поскольку вы пишете краткое изложение функции, которая выполняет очень мало. Очень часто формальные элементы (параметры и типы возвращаемых данных) и сводка повторяют друг друга. Я не уверен, как это повторение не проходит "полезный" тест. Возможно, если есть Что-то отсутствует , вы можете добавить это. Не стесняйтесь расширять и писать больше - ничто не мешает вам писать «полезную» документацию, которая больше, чем минимум.
Избыточность - хотя и утомительная - кажется, не может быть бесполезной.
Помните, что ваши комментарии будут создавать индексы, а также обычные текстовые страницы. Формально структурированные части имеют важное значение для индексации и форматирования.
Для более сложных классов (и функций), сводка - это место, где можно расширить нюансы. Например "почему?" или «когда это можно и нельзя использовать», и «другие ограничения» и «примеры кода» и тому подобное, что было бы более полезным.
В любое время вы можете - и должны - написать больше , чем минимум. Однако для тривиальных функций
Jayrdub:
Имейте в виду, что пункт этих комментариев заключается в создании документации для вашего кода. Избыточность в порядке, так как разные части этих комментариев могут использоваться по-разному в разных сценариях - не весь ваш комментарий может использоваться в определенных обстоятельствах.
Хотя документ XML полезен для создания файлов справки в стиле MSDN, он также широко используется в intellisense и подсказках в Visual Studio. Ваше резюме будет видно в определенное время, ваши теги параметров будут видны в другое время, а ваш возвращаемый тег будет виден в другое время. Иногда они все будут видны вместе, а иногда нет.
Короче говоря, избыточность полезна . Он помогает вам как программисту в различных обстоятельствах, когда вы используете метод или класс, который он документирует.
Если его навязывают вам, то вам, возможно, придется просто страдать с некоторыми повторение, поскольку вы уже используете хорошие методы самодокументирования, такие как интеллектуальное именование.
Другие полезные вещи, которые вы могли бы включить в документацию: 1) Форматирование. Существуют ли какие-либо ограничения на userID, например, «Все пользователи ниже 500 являются администраторами» или что-то в этом роде? Это хорошо, чтобы прокомментировать с параметром.
2) Исключения - Если ваш метод собирается бросить или передать один, документируйте его, чтобы люди, использующие его, знали, как с ним работать.
3) Примеры кода - показывающие, как использовать ваш метод
4) Особые условия - будет ли возвращаемый объект находиться в каком-либо нечетном состоянии? Если идентификатор пользователя не найден, вы возвращаете пустое или пустое / error PersonalInfoDTO?
И, конечно, на простых методах может показаться, что имеется много избыточной информации, но более сложный код может извлечь огромную выгоду из тщательная документация.
Я склонен очень подозрительно относиться к инструментам, которые заставляют вас добавлять комментарии в самых произвольных местах.
Не поймите меня неправильно, я сильный сторонник комментариев. Но комментарии, подобные тем, что в вашем примере, являются чистым «шумом»: они не добавляют ничего полезного, и любая значимая информация, если таковая имеется, скрыта за пухом.
Если комментарии могут быть сгенерированы автоматическим инструментом ... тогда люди вообще не имеют права писать их. Если это является обязательным по какой-либо другой причине (например, создание внешней документации), у вас должен быть какой-то автоматизированный сценарий для их генерации и размещения результатов в ненавязчивом месте.
Конечно, есть много значимых вещей, которые вы могли бы сказать об интерфейсе этой функции. Каковы границы параметров, например.
There is a lot of repetition - the worst IMHO is Properties, where you are supposed to fill in the
I try to briefly summarise the property/method in the summary but put more detailed descriptions in the ,
The second thing I do is use an add-in I've written to auto-generate and auto-update) the Doc comments, so that I minimise the work involved in documenting the code - if an automated tool can fill in most of the details for me, it minimises the effort involved in maintaining this "duplicated" information. It also auto-formats and word-wraps the comments to keep them tidy.
See http://www.atomineer.com/AtomineerUtils.html for more information and a free download.
Вы можете сделать его полезным:
/// <summary>
/// Gets the user's personal information.
/// </summary>
/// <remarks>
/// We need this data transfer object in order to bridge Backend.SubsystemA
/// and Backend.SubsystemB. The standard <see cref="PersonalInfo"/> won't
/// work.
/// </remarks>
/// <param name="userId">Integer representing the user's ID.</param>
/// <returns>
/// <see cref="PersonalInfoDTO"/> representing the user, or <c>null</c>
/// if not available.
/// </returns>
public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...}
Для меня резюме - это информация высокого уровня "какова цель этого метода", отмечает для дальнейшего объяснения, и см. , где вы можете легко перемещаться по вашей документации. Каждый из них добавляет ценность.
Я действительно люблю комментарии к документации благодаря ReSharper . Я переназначил команду QuickDoc на CTRL + SHIFT + Q .
If you're doing Java, you must be careful about complete documentation - the more you document, the less chances there are that users would find the things that are actually relevant. Adding extra markup only makes it worse.
You may want to consider only capturing "directives" or at least highlighting them very strongly.
See my detailed reply on "tips for writing a great javadoc" that are based on my Ph.D. research on this topic.
Проблемы заключаются в следующем ....
- Верно. Никто не мешает вам писать комментарии, но их становится труднее поддерживать. Кто-то, читающий код, может запутаться, если комментарий не соответствует коду. Признайтесь, мы все меняем код позже и забываем / у нас нет времени обновлять их.
- Некоторые методы действительно очень просты и не нуждаются в комментариях.
- Труднее прочитать 1000 строк, чем 100 строк правильно написанного кода. Да, даже с визуальной студийной раскраской
- Требуется много времени, чтобы прокомментировать КАЖДЫЙ ОДИН МЕТОД в вашем коде.
- Эти комментарии подходят, если вы создаете библиотеку, но не для чего-то, что нельзя повторно использовать ... например, небольшое приложение Silverlight .