Должны все открытые методы API быть зарегистрированными? [закрытый]

a) Всегда документ.

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

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

b) Зарегистрируйте все, что не очевидно, или когда в сомнении. В этом случае:

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

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

Извините, что Бессмысленно повторил, но Всегда зарегистрировал.

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

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

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

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

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

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

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

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

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

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

a)

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

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

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

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

Я должен смочь посмотреть на метод и знать:

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

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

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

Просто мои два цента.

a)

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

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

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

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

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

clearAutoscroll

protected void clearAutoscroll()

clear autoscrolling

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

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

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

a)

Если это - метод, всегда существуют некоторые небольшие детали, которые имеют значение, например, те Вы обеспечили относительно сбрасывания и закрытия потоков. Например, метод "Представляет getFileExtension в виде строки (Представьте имя файла в виде строки)", кажется, не нуждается в документации, но что, если "имя файла" не имеет расширения? Тот ответ должен быть зарегистрирован.

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