Welcome to the Treehouse Community

Want to collaborate on code errors? Have bugs you need feedback on? Looking for an extra set of eyes on your latest project? Get support with fellow developers, designers, and programmers of all backgrounds and skill levels here with the Treehouse Community! While you're at it, check out some resources Treehouse students have shared here.

Looking to learn something new?

Treehouse offers a seven day free trial for new students. Get access to thousands of hours of content and join thousands of Treehouse students and alumni in the community today.

Start your free trial

JavaScript JavaScript Functions Arrow Functions Descriptive Comments for Functions

Is JSDoc needed

For JavaScript I've been commenting using // for single lines and /* / for multiline but i've recently found that we use /* **/ and

  • @param
  • @returns

Is this purely commenting only? Does this have or add any functionality to any programs?

Please feel free to comment.

Thanks :-)

5 Answers

jasonj7 This is purely documentation. It does not add any functionality to the program, however, future employers will be impressed if you make a good habit of documenting your code. It is a very good idea to help you remember how the code is working if you revisit it a long time after writing it. It is also helpful to other programmers who might need to make adjustments in your code, therefore, it is a best practice to always comment and document your code properly.

it is important to document your work, so if and when you leave the company you design the code for would be able to review it and understand it,

J A
seal-mask
.a{fill-rule:evenodd;}techdegree
J A
Full Stack JavaScript Techdegree Student 4,646 Points

Great question. I just wanted to add my two cents, having been a professional developer for a some years now. Strictly speaking, no the JSDoc is not needed for your functions. Technically no comments are needed in any program.

However, comments provide invaluable documentation not just for your other coworkers but even for yourself, when you return to an application or piece of code you may have written months or even years ago. It gives context to people so they don't have to guess why you did something a certain way. On top of that, JSDoc is a standard way of documenting your functions and these special comments can even be consumed by other tools to make nicely formatted PDF or HTML pages that document an API.

Personally I don't consider my work done in a class or application until all the major public functions and methods have some sort of documentation. When reviewing other people's code in GitHub for example, comments make understanding the code much easier and allow for me to finish reviews much more quickly.

Jacob Kruse
Jacob Kruse
5,069 Points

One thing that people seem to forget about jsdoc and other comment/documentation systems like this is that when you use most IDEs and you type the function name in your code you will get a tooltip that will show you all the params that you have available in that function. Later you will learn about overloading functions, this is where you can have different function declarations with different params but for the same function names. I am not sure if JS has this but in C# and many languages you can do this and these tooltips help amazingly.

Aaron Loften
Aaron Loften
12,864 Points

Ima necro-post because this is kinda an important topic for me and newbies will come in later and see this. Ive been doing web dev for over ten years and have seen all kinds of random tools used for commenting - both manual and automated. Over-commenting(commenting too much or when it is not needed) was very important when I first started for several reasons.

However, I have seen more and more groups try to move AWAY from unneeded commenting. Now, commenting should ONLY be left for confusing functions or longer functions that are confusing at first glance.

INSTEAD...try a technique that is called "Self-documenting code" which is the process of naming everything properly. For example, if a function adds two numbers together, maybe call it...

  //this is good - no comments needed
  function add(firstNumber, secondNumber) {
    return firstNumber + secondNumber;

  }

...in this example, we call the function "add" because we plan to add it. We call the first number "firstNumber" because its the first number. Using self documenting code is better than doing something like...

  //this is bad - many comments could be needed for a different developer to understand why your code has bad naming practices
  function getIt(a, b) {
    return a+b;

  }

The goal should be to write code that is easy to read. If you have a long function, consider breaking it into smaller pieces; create new functions with those pieces and call those functions from within your main function.

Its also worth noting that when looking at JSDoc, you will notice how their comments are unneeded. It tells you that a title is a title and an author is an author. I think because it is named properly, it would not need comments, which would dilute the legibility of the page by repeating information which goes againts the DRY principle.

I teach a lot of newbies and this is one of the first things I un-teach. "Stop commenting like crazy and only comment when its confusing. Instead, name things correctly, break up large chunks of code, and use objects to store data when possible because it is a very clean way to be specific."

More than anything, its not important to do JSDoc or to do Self-documenting code. Instead, it is important to be willing to learn whatever the employer uses. This is how you learn.