current community

your communities

more stack exchange communities

Stack Exchange Inbox Reputation and Badges
tour help
Sign up ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free.
up vote 9 down vote favorite
2

This question already has an answer here:

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?

share|improve this question

marked as duplicate by durron597, MichaelT, gnat, Ixrec, Snowman 2 hours ago

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.
1  
@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 23 hours ago

4 Answers 4

up vote 11 down vote accepted

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.

share|improve this answer
    
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. –  Jonathan Todd 23 hours ago
5  
@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 18 hours ago
    
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. –  Jonathan Todd 6 hours ago
    
@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 5 hours ago
up vote 16 down vote

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.)

share|improve this answer
    
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 11 hours ago
    
@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 10 hours ago
up vote 8 down vote

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.

share|improve this answer
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. –  MainMa 16 hours ago
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 15 hours ago
up vote 1 down vote

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.

share|improve this answer

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