Javascript-форум (https://javascript.ru/forum/)
-   Оффтопик (https://javascript.ru/forum/offtopic/)
-   -   Как комментировать функции? (https://javascript.ru/forum/offtopic/35723-kak-kommentirovat-funkcii.html)

megaupload 20.02.2013 09:48

Как комментировать функции?
 
Мне кажется лучше делать так

//Отправляет сообщение
function sendMessage(){

}


//Отправить сообщение
sendMessage();


А как комментируете вы?

ksa 20.02.2013 10:07

Цитата:

Сообщение от megaupload
А как комментируете вы?

// Делает то-то
function primer(Val1,Val2,...,ValN){
   /*
   Val1 - означает то-то
   Val2 - означает то-то
   ...
   ValN - означает то-то
   */
}


// Сделать то-то
<последовательность_действий>;

danik.js 20.02.2013 10:14

/**
 * Создает экземпляр Circle.
 *
 * @constructor
 * @this {Circle}
 * @param {number} r Радиус окружности.
 */
function Circle(r) {
    /** @private */ this.radius = r;
    /** @private */ this.circumference = 2 * Math.PI * r;
}
 
/**
 * Создает новый экземпляр Circle по диаметру.
 *
 * @param {number} d Диаметр окружности.
 * @return {Circle} Новый объект Circle.
 */
Circle.fromDiameter = function (d) {
    return new Circle(d / 2);
};
 
/**
 * Подсчитывает длину окружности
 *
 * @deprecated
 * @this {Circle}
 * @return {number} Длина окружности.
 */
Circle.prototype.calculateCircumference = function () {
    return 2 * Math.PI * this.radius;
};
 
/**
 * Возвращает длину окружности, вычисленную заранее.
 *
 * @this {Circle}
 * @return {number} Длина окружности.
 */
Circle.prototype.getCircumference = function () {
    return this.circumference;
};
 
/**
 * Строковое представление объекта Circle.
 *
 * @override
 * @this {Circle}
 * @return {string} Информация об объекте Circle.
 */
Circle.prototype.toString = function () {
    return "A Circle object with radius of " + this.radius + ".";
};

ksa 20.02.2013 10:53

danik.js, интересно... Зачем * на каждой строке?
Теперь ведь почти каждый редактор подсвечивает коментарии... Т.е. их и так видно.

danik.js 20.02.2013 10:59

http://ru.wikipedia.org/wiki/JSDoc

danik.js 20.02.2013 11:03

Цитата:

Сообщение от ksa
Зачем * на каждой строке

Notepad++ например сам ставит их на каждой строке. Хотя может это из-за какого-то плагина.

ksa 20.02.2013 11:05

Цитата:

Сообщение от danik.js
Notepad++ например сам ставит их на каждой строке.

Мой не ставит... Стандартная установка с оф.сайта...

Gozar 20.02.2013 12:13

Коментирую только методы и очень неочевидные блоки. Остальное как сказано выше:
Цитата:

Сообщение от nasqad
имя функции должно отражать ее функционал


kobezzza 20.02.2013 12:31

Комментирую все функции по стандарту JSDoc GCC. Профит в том, что потом можно юзать GCC как валидатор коду + проще юзать advanced mode, а также по таким комментам легко делать генерацию доки в HTML.

Некоторые IDE, например WebStorm, умеют использовать такие доки для "умного" автокомплита, т.е. также как и у типизированных языков без необходимости подключения специальных библиотек.

megaupload 20.02.2013 13:08

Цитата:

Сообщение от ksa
Зачем * на каждой строке?

потому что это jsdoc


Цитата:

Сообщение от nasqad
Не комментирую функции, имя функции должно отражать ее функционал

а если английский не знаешь
Цитата:

Сообщение от kobezzza
Комментирую все функции по стандарту JSDoc GCC. Профит в том, что потом можно юзать GCC как валидатор коду + проще юзать advanced mode, а также по таким комментам легко делать генерацию доки в HTML.

Некоторые IDE, например WebStorm умеет использовать такие доки для "умного" автокомплита, т.е. также как и у типизированных языков без необходимости подключения специальных библиотек.

бро)

danik.js 20.02.2013 13:11

Вот он, вот он - срыватель покровов! Мы ждали тебя! Спасибо кэп, что пришел и всем все разъяснил!

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

Shaci 20.02.2013 13:24

Цитата:

Сообщение от megaupload
а если английский не знаешь

тогда нехуй программировать

ksa 20.02.2013 13:27

Цитата:

«У кого нет миллиарда, могут идти в жопу» — так приветствовал своих гостей президент Mirax Group Сергей Полонский.
:haha:

megaupload 20.02.2013 13:55

Цитата:

Сообщение от Shaci
тогда нехуй программировать

вот вот

melky 20.02.2013 14:19

Цитата:

Сообщение от kobezzza (Сообщение 235764)
Комментирую все функции по стандарту JSDoc GCC. Профит в том, что потом можно юзать GCC как валидатор коду + проще юзать advanced mode, а также по таким комментам легко делать генерацию доки в HTML.

Некоторые IDE, например WebStorm, умеют использовать такие доки для "умного" автокомплита, т.е. также как и у типизированных языков без необходимости подключения специальных библиотек.

люто плюсую, JSDOC неплохо помогает для "компиляции" кода из понятного (dev) в быстрый (adv-min).

кстати, какие флаги GCC вы используете? у меня такие :

// вывод сообщений минификатором, если что-то не так
warning_level: 'VERBOSE',
// я пишу в строгом режиме 
language_in: 'ECMASCRIPT5_STRICT',
// продвинутый режим - наше все
compilation_level: 'ADVANCED_OPTIMIZATIONS',
// использовать типы для оптимизации - типы берутся из JSDOC
use_types_for_optimization: null,
// вывод о качестве минификации и ошибках в конце минификации
summary_detail_level: 3,
// оборачивать исх. код в анонимную функцию - продвинутый режим иногда убивает ее.
output_wrapper: "'(function(){%output%})();'",


Цитата:

Сообщение от megaupload
потому что это jsdoc

nope sir

JSDOC - это вот:
/**  две звездочки в начале  */

а эти звезды на каждой строке - красивости Jetbrains и др.

megaupload 20.02.2013 14:35

я это и имел ввиду

ksa 20.02.2013 15:05

Цитата:

Сообщение от megaupload
я это и имел ввиду

А я не это. :D

kobezzza 20.02.2013 15:34

Цитата:

Сообщение от melky (Сообщение 235821)
кстати, какие флаги GCC вы используете? у меня такие :

// вывод сообщений минификатором, если что-то не так
warning_level: 'VERBOSE',
// я пишу в строгом режиме 
language_in: 'ECMASCRIPT5_STRICT',
// продвинутый режим - наше все
compilation_level: 'ADVANCED_OPTIMIZATIONS',
// использовать типы для оптимизации - типы берутся из JSDOC
use_types_for_optimization: null,
// вывод о качестве минификации и ошибках в конце минификации
summary_detail_level: 3,
// оборачивать исх. код в анонимную функцию - продвинутый режим иногда убивает ее.
output_wrapper: "'(function(){%output%})();'",

compilation_level: 'ADVANCED_OPTIMIZATIONS', use_types_for_optimization,
--externs (если нужно), а остальное дефолтные настройки

FINoM 21.02.2013 03:34

Цитата:

Сообщение от danik.js
Notepad++ например сам ставит их на каждой строке. Хотя может это из-за какого-то плагина.

Какого плагина? Давно ищу.

danik.js 21.02.2013 09:46

Цитата:

Сообщение от FINoM
Какого плагина?

В меню плагинов вижу DocIt. В списке установленных плагинов такого нет. Есть Notepad#, там в что-то говорится о комментариях для различных языков. Новерно это он и есть - Notepad#

FINoM 21.02.2013 21:16

danik.js, спасиб.


Часовой пояс GMT +3, время: 08:00.