Лучшая практика для документирования зависимостей библиотеки javascript

Итак, вы создаете кучу кода во внешнем файле .js, который требует jQuery и несколько его плагинов, или MooTools, или, возможно, еще несколько эзотерических библиотек. Очевидно, что фактическое "включение" выполняется на главной HTML-странице в разделе HEAD при загрузке в каждом script.

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

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

Ответ 1

jQuery UI добавляет зависимости своих виджетов в заголовке файла:

/*
* jQuery UI Effects Bounce @VERSION
*
* Copyright 2011, AUTHORS.txt (http://jqueryui.com/about)
* Dual licensed under the MIT or GPL Version 2 licenses.
* http://jquery.org/license
*
* http://docs.jquery.com/UI/Effects/Bounce
*
* Depends:
* jquery.effects.core.js
*/

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

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

if(!$.isFunction($.fn.dialog)) {
    throw "Could not find jQueryUI dialog. Please include jQuery UI";
}

Таким образом, ваш script не должен полностью ломаться, если необязательная зависимость не выполняется.

Ответ 2

Для разработчиков Visual Studio там вы можете попробовать блоки, подобные этим в своем заголовке

/// <reference path="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.6-vsdoc.js" />
/// <reference path="thirdparty/ba-debug.js" />
/// <reference path="thirdparty/underscore.js" />

Пока это не разрешает ваши зависимости, оно документирует их, и оно дает вам intellisense в Visual Studio...

См. http://msdn.microsoft.com/en-us/library/bb385682.aspx, затем найдите Директивы о ссылках (без имени или идентификатора, чтобы напрямую ссылаться, извините...)

Ответ 3

Мои заголовки js выглядят следующим образом:

////////////////////////////////////////////////////////////////////////////////
//
//  src:        www.someDomain.com/js/modules/etc
//  author:     someguy
//  date:       6-22-11
//  intent:     what is the purpose / use of this module
//  package:    prototype parent
//  requires:   jquery.1.4.js
//              fancybox
//              etc
//
////////////////////////////////////////////////////////////////////////////////

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

Ответ 4

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

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