I hear the voice of the cons guys who think that semantic names (for function, class, variables, ...) is sufficient. Yes and no; anybody who wants to contribute to your project, open-source or commercial, must be able to understand what you've done in a seamless way. In the end, it's all about being inclusive :wink:
The idea is to follow this simple rule (kind-of standard):
- Write a “big” descriptive comment for “big” code entities. For example, Classes, Objects (in OO), methods, service, models, etc using
/* ... */
- Write a “small” single-lined comment for smaller entities like important variables, conditions, etc using
When I say there is no strong standard for comments, it's not true, there is JSDoc. It's just that JSDoc is often perceived as the untrendy documentation tool for old JS devs and not used as much as it must. Anyway, I think JSDoc is the best practice so far, even if you don't want to generate documentation based on your comments, it will give you enough conventions to build strong and standards comments.
Because we all love functional programming, each method must be decently commented to keep your code understandable, even for yourself in the future.
— WTF?!? Six lines of comments for five of “real” code!
— Yep, huge investment, but it's for future generations :kissing_heart:
As you can see, JSDoc provide a way to describe what came in and out, but also which types are required. Properly configured, your IDE can use those comments to type check your code, almost like TypeScript and Flow does.
Read the (JS) doc, please!
I can show you all the possible examples, it will never be as clear as the JSDoc doc is. We must admit that it's not the sexiest documentation out there, but it's very accessible and not only for JS purists or old school devs. Feel free to take a look to all the block tags that JSDoc has to offer to unleash its power.
I agree it's very verbose and not really fun to write the base canvas. So there are a lot of good tools to help you write your comments. Here are some examples for VSCode, but I'm sure there are similar modules for Atom, Sublime or any code editors:
- Preview JSDOC by Ludovic Dorival : if you're interested of the JSDoc documentation generation, it's a very simple way of previewing it.
- Todo Tree by Gruntfuggly : because comments can be used for delayed tasks, this plugin will help you find all your
- Rewrap by stkb : having more than 80-100 characters per line of comment is often (always) a bad idea, this plugin will help you to transform it into multiple lines.
- vscode-fileheader by mikey : you're maybe a fan of signing each file, with that plugin, it will be easier with automatic date update.
There is surely a ton of other great resources for you to live an easier comment writer's life, feel free to take a look around and found what suits you the most.
No big and deep speech here, just keep in mind that this extra effort of writing clear and standard comments will help others who will work on your code, but also your future self and that's maybe the biggest benefit.