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

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

15 голосов
/ 22 июня 2011

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

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

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

Ответы [ 4 ]

7 голосов
/ 22 июня 2011

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

/*
* 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";
}

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

6 голосов
/ 13 сентября 2011

Для разработчиков 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" />

Хотя это не разрешает ваши зависимости, оно документирует их и дает вам интеллектуальный смысл в Visual Studio ...

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

3 голосов
/ 22 июня 2011

мои заголовки 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
//
////////////////////////////////////////////////////////////////////////////////

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

0 голосов
/ 13 сентября 2011

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

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

...