Question

我希望添加有用的评论，而不是太冗长。在回答想象之前，将Javascript函数隐藏在数百或数千行源代码中。另请注意，在评论中，我通过更好地描述其用法而不是使用实际的参数名称，给函数参数更多一点意义。我这样做是为了更好地指导可能在以后需要重构或修改脚本的用户（程序员）。

    var ctx = getCanvas();// getCanvas(width, height)
    grid(ctx);// grid(context, element size, line width, line color)

    function getCanvas(width = 200, height = 150) {
        // code to run
    }

    function grid(ctx, elSize = 10, width = .3, color = 'green') {
        // code to run
    }

Answer 1

您要做的是使用 JSDoc 以获得更好的可读性

/**
 * describe your function
 * @param {number} width - describe your parameter
 * @param {number} height - describe your parameter
 * @return {type} describe your returned value/object
 */
function getCanvas(width = 200, height = 150) {
    // code to run
}

这对你的IDE也很方便

Answer 2

好吧， Its always good to have your code properly commented.

在函数开始之前添加标准/描述性注释，而不是注释行。

有很多方法可以在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

来源： - Does JavaScript have a standard for commenting functions?

希望这会对您有所帮助：）

Answer 3

困难的问题，因为它取决于您自己的偏好，您还必须考虑其他开发人员将来必须阅读您的代码。

我个人得到了一些评论疲惫的评论＆＃34;有些方法，但其他人会说你不够评论。我认为函数和变量的良好命名约定通常可以消除对大多数注释的需要。

Answer 4

评论是编程的好方法，所以在我看来，它让代码更加干净。例如，当您的代码需要维护时，其他程序员就会理解。我认为你需要评论的是你认为对其他人有什么理解，并试图明确。

Javascript用法，这些好评还是有点过分？

4 个答案: