Должен ли я документировать «обратный обратный вызов()» в качестве возвращаемого значения, если он не предназначен для использования?

Question

У меня есть кусок кода, который не возвращает ничего полезного:

/** 
* Close the web server 
* 
* @param {function} callback - Called after web server is stopped 
*/ 
PolyApp.prototype.stop = function(callback) { 
    if (!this._listeningServer) { 
    if (callback) { 
     return callback(); 
    } 

    return; 
    } 

    this._listeningServer.close(callback); 
}; 

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

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

С другой стороны:

• Я возвращаю значение, которое не документированный

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

Что вы думаете о? Правильно ли я прагматичен?

Answer 1

Что вы хотите документировать, зависит от вас. Вы должны задать себе вопрос: «Будет ли мне, или другим людям, когда-нибудь понадобиться, чтобы эта документация получила дополнительные знания?». В случае обратных вызовов, которые не требуют какого-либо конкретного поведения возврата, вам не нужно документировать что-либо из этого. Вы должны указать для stop, что он вернет все возвращаемые обратные вызовы. Люди могут запутаться иначе.