Есть ли у JavaScript стандарт для комментариев?

В настоящее время я пишу код JavaScript на стороне клиента и задаюсь вопросом, как комментировать мои функции.

Я исхожу из фона С#, где есть официально рекомендованный стиль комментариев документированный Microsoft, который я следую, что позволяет компилятору и другим инструментам автоматически генерировать документация.

Аналогично, PHP PHPDoc-стиль является вездесущим и на пути к тому, чтобы стать официальным стандартом, рекомендованным PHP-FIG.

Аналогично ли у JavaScript есть общепринятая инструментальная цепочка, стандарт или набор лучших практик, которые я могу применить при комментировании моих функций?

ОТВЕТЫ

Ответ 1

Вы можете использовать jsdoc стиль, который позволит вам создавать документацию позже

так

/**
 * Adds two numbers
 * @param {Number} a 
 * @param {Number} b
 * @return {Number} sum
 */
 function sum(a,b) { 
   return a + b;
 }

РЕДАКТИРОВАТЬ: Если вы используете AngularJS, вы можете ссылаться http://google.github.io/styleguide/angularjs-google-style.html

Ответ 2

Ну, есть много способов добавить комментарии в javascript; Вот моя рекомендация .

с использованием // лучше, чем /* */, потому что тогда вы можете использовать последний, чтобы вынуть весь блок, содержащий другие комментарии. Однако, если вы хотите использовать инструмент создания автоматической документации, вы должны использовать комментарии, похожие на стиль javaDoc.

Это пример, который будет работать с YUI DOC (лучший) http://developer.yahoo.com/yui/yuidoc/#start

/**
* This is a description
* @namespace My.Namespace
* @method myMethodName
* @param {String} str - some string
* @param {Object} obj - some object
* @param {requestCallback} callback - The callback that handles the response.
* @return {bool} some bool
*/
    function SampleFunction (str, obj, callback) {
         var isTrue = callback(str, obj); // do some process and returns true/false.
         return isTrue ;
    }

Другие параметры Примеры: - http://usejsdoc.org/tags-param.html

Надеюсь, это поможет вам:)

Ответ 3

Стандартом, к которому я привык, является JSDoc: https://github.com/jsdoc3/jsdoc

Он похож на javadoc, если вы знакомы с этим.

Ответ 4

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

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

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

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