10

I was researching proper commenting practices for JavaScript and highly upvoted answer (+100) cites JSDoc-like commenting. JSDoc promotes comments like this:

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

From my understanding, good comments should explain "why" not "what" and the above looks like alot of "what" to me.

Why should JavaScript be commented / documented in this way, and how does this relate to the popular "why, not how" commenting policy?

marked as duplicate by durron597, user40980, gnat, Ixrec, user22815 Sep 19 '15 at 21:16

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

  • 2
    @durron597 I don't believe this is a duplicate, because that question is about Java, a statically typed language, and this one about javascript, which is dynamically typed. Documentation is less important in static languages as type annotations can make the code more self-documenting. – Jules Sep 18 '15 at 23:56
15

The target audience for internal comments is code maintainers. Code maintainers should be able to tell "what" from the code itself.

The target audience for external comments is code consumers. Code consumers don't care about "why," since they are using the code, not editing it. Thus, external comments tend to answer "what." Code consumers need very explicit documentation, since they need to figure out which function to call, not how those functions work.

  • 1
    Hmm.. So I suppose I should comment this way even if I'm working on a project by myself. It would seem best practice probably suggests planning for the eventual possibility that a project could grow to that point. – Viziionary Sep 18 '15 at 23:58
  • 8
    @JonathanTodd: You are both a code consumer and a code maintainer of your own code, so your code should have proper internal and external comments. Of course, if only one person is maintaining and consuming your code, proper documentation is less important. However, working on a project by yourself usually still includes at least two programmers, Present-Jonathan and Future-Jonathan. It's up to Present-Jonathan to document the code well enough that Future-Jonathan can successfully maintain and/or consume it. – Brian Sep 19 '15 at 5:41
  • Ok I see! So a code consumer could be another engineer on my project, and even if my code is self-documenting, it isn't time efficient for every code consumer to spend the time reading the code and its implications to determine the required parameter types and method usage. I think I get it now. – Viziionary Sep 19 '15 at 17:40
  • @Brian: I would suggest adding that just because you are the coder/writer doesn't mean that you can't also be the code consumer at a later date or in a seperate part of the project. – jmoreno Sep 19 '15 at 18:22
18

This isn't a comment. It's documentation, which, because ECMAScript doesn't support documentation as a language feature, is written inside a comment.

Note that "documentation comments" like this are fundamentally different from "normal" comments: comments are ignored by the parser, they don't even reach the later stages of the compiler/interpreter. They are essentially whitespace.

Documentation comments however, are processed. They aren't processed by the compiler/interpreter, but they are processed by the IDE or static analyzers. (And obviously also documentation generators.)

  • Since Javascript doesn't contain any static typing information, but specific types are frequently expected, I believe this answer explains the functional need for these comments. – Patrick Sep 19 '15 at 12:14
  • @Patrick: yes, indeed. Type annotations in languages which don't have them are also often put in comments. Or, in this case, are part of the documentation syntax. Other things are: unit tests, contracts, machine-checkable proofs of correctness, DB schemata corresponding to the code in question that are automatically generated from the comments etc. – Jörg W Mittag Sep 19 '15 at 13:46
8

JSDoc is intended for generating documentation that's read separately from the code. Even if the code is self-documenting, it will not help the reader of the generated documentation, because he may or may not have access to the code.

  • 1
    Is it? As I understand it, the documentation will contain the signature of the method, that is the name of the method and the names of arguments. From this point of view, the comments of @param in OP example are completely useless. – Arseni Mourzenko Sep 19 '15 at 7:26
  • 2
    @MainMa in this particular toy example it is quite obvious what each parameter in method signature means, but in real applications it usually isn't, and the documentation needs to clarify important assumptions about the meaning and structure of each parameter, what input values are/aren't acceptable there, etc. The expected/allowed types of input and output values are also very important, and in a language like JavaScript it needs to be added explicitly - without these comments, the method signature in generated documentation wouldn't contain the types, so they're not useless even here. – Peteris Sep 19 '15 at 7:55
1

In addition to the other answers, it's also helpful for IDEs that can help with code-completion features from source or library files. This is true for any language really though.

Not the answer you're looking for? Browse other questions tagged or ask your own question.