Следует ли документировать все общедоступные методы API?

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

а) Всегда документируйте.

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

Я выбираю a только потому, что, исследуя класс, мне нравится видеть документированные общедоступные методы (в javadoc или аналогичных). Это немного проясняет некоторые вещи. Но каждому свое.

Публичный метод Каждый должен быть задокументирован.

Именно здесь я обычно повторяю мантры «в обе стороны в гору, когда я был ребенком» о документировании только тогда, когда ваш босс просит вас НО ... в последнее время я изменил свою мелодию. Я думаю, что это ключевой, чтобы предоставить подробную документацию по каждому общедоступному методу, когда вы работаете над проектом с открытым исходным кодом, библиотекой, которую обычно называют, или заранее знаете, что кому-то еще придется тесно сотрудничать с интерфейсами, которые вы предоставляете .

Документация делает код поддерживаемым, но, как и все остальное, вы можете перестараться и тратить время на написание комментариев, POD и вики, когда вам нужно работать над добавлением функций и прохождением модульных тестов. Это рассматривается в Agile-манифест (то есть: личное общение лучше, чем документация, и так далее по лестнице методов интерфейса).

а)

Если это метод, всегда есть некоторые мелкие детали, которые имеют значение, например, те, которые вы указали относительно очистки и закрытия потоков. Например, метод «String getFileExtension (String filename)» не требует документации, но что, если «filename» не имеет расширения? Этот ответ должен быть задокументирован.

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

а)

Как уже упоминалось, вы можете создавать документацию, и это помогает в обслуживании.

Кроме того, Intellisense извлекает выгоду из того, что сообщает, что делает метод / свойство.

а)

Дополнительным преимуществом предварительной тщательной документации является предотвращение изменений в поведении метода с течением времени. В этом примере вы цитируете предложение о сбрасывании, а не о закрытии потока, может быть ценным - я бы сказал, что этот уровень детализации является важной семантикой, которую должен знать пользователь метода. Если это не было задокументировано, то более поздняя реализация API может не выполнять сброс, что может привести к непредсказуемым результатам для пользователя метода.

Каждый публичный метод (и поле) действительно должен быть задокументирован специально для API. Кроме того, документация по методу должна быть достаточно ясной и информативной, чтобы доступная информация не оставляла места для двусмысленности.

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

По большей части я рассматриваю Спецификацию Java API как отличный пример, однако есть некоторые части, которые, как я заметил, не так хорошо документированы и / или информативны. Возьмем, к примеру, класс DropTarget. У него есть метод под названием clearAutoscroll(), и javadoc для этого метода:

clearAutoscroll

protected void clearAutoscroll()

clear autoscrolling

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

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

Я должен уметь взглянуть на метод и знать:

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

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

Я не думаю, что вам нужно переусердствовать с документацией и думать, что хорошо подобранные методы, имена аргументов и т. д. Имеют ДОЛГОЙ путь к удобочитаемости. Но когда вы пишете метод, для его документирования требуется всего несколько секунд - может быть, максимум минуты. Я не вижу веских причин не делать публичный интерфейс понятным и документировать его там, где это необходимо. Возможно, если это «одноразовая» библиотека ... но я не пишу слишком много из них.

Всего два цента.

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

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

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

Всегда документируйте.

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

Также для полноты документации.

Простите Parrot, но всегда документируйте.

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

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

Поэтому я просмотрел документ, задокументировал все свои функции, изложил все необходимое форматирование входных данных и написал дополнительный документ о том, как приложение должно выполнять свои задачи. Я уволился с этой работы более чем на 3 года и до сих пор говорю об этом программном обеспечении, когда им нужно что-то конкретное (последний раз 6 месяцев назад). Это было меньше, чем Клок (1000 строк кода), но он все еще был достаточно сложным, чтобы вызывать вопросы два с половиной года спустя.

б) Задокументируйте все, что не является очевидным или сомнительным. В этом случае:

/** Copies all readable bytes from inStream to outStream. outStream will be flushed, 
 *  but neither stream will be closed.
 */

Вы уже написали, что inStream - это InputStream, и вам не нужно указывать, что он предназначен для чтения байтов в собственном комментарии, как вы уже сделали это в комментарии функции.

Документируйте только те методы, которые вы хотите, чтобы люди могли использовать и использовать эффективно.