@11:54 you hover over the buildURL fn to show the comments that you placed. However you'll notice that your @return statement was blank. You have to remove the curly brackets to get it to show. There may be a better way to get it to show---> if there is PLEASE tell me.
well, I see that it's not showing in the bottom section BUT it does populate the top section. I was partially wrong. Is there a way to see the types in the bottom section too?
@@meisterunner I hadn't noticed the missing type in the message box. The type does appear when you mouse over the variable - let url. If you add messages after the {URL}, those appear. You can write the datatype there too and it appears in the box. It is an error in the parsing of the datatype by VSCode. The curly braces are needed to identify the datatype. Without them it is viewed as just a message. I would recommend that you go to the help menu and select "Report an Issue". Get credit for finding the bug.
I'm interested in this only because I'm making a public API and this is a mechanism that's easy to deliver documentation to developers and Copilot. I have seen some repositories where this was extremely overused with redundant and pointless comments, and even inaccurate comments. But it's a very, very good tool for highly used and well-maintained APIs.
I've jet to see any code that got easier to navigate with comments. I don't put any comments in, I rather use names for variables and functions that are self explanatory. Since i'm more of functional programming kind of guy, the code tells you best what it's doing. This type of "documentation" looks insane to me. You can infer all the information just looking at the code.
Good code does indeed use an excellent naming convention. It will also follow a style guide that your team agrees on. It will also be well commented and documented. This was a small contrived example of how to use JSDoc to help that process. Comments always improve code, if not for you then for the people you work with. Your code and your names might make sense to you. Doesn't mean they make sense to everyone else.
@@SteveGriffith-Prof3ssorSt3v3 I can imagine that there is a scale of project, where this becomes useful. But to be honest, specially in JS development those are so rare that it doesn't make too much sense to conform to a paradigm in smaler scale projects in which they hinder more then help. So many younger programmers are way to hung up on best practices, preparing for a role they might never play. And even then, in large scale projects, documentation always lags behind to the extend that the product shipped with docs being only half ready, and never looked at ever again. Not saying that it's always useless, but very very often it is. Another usecase for documentation is for libraries, but there, you want examples showing how to use the lib, but a list of methods and properties with potentially misleading descriptions. And you can always list methods and properties in the dev-console if you want to dig for things the docs didn't say (which is the case almost always). So yeah, the argument here is "docs would be cool, if they were complete, which they never are". Another argument i stole from UI design. The more you tell the user what to do, the more likely it is he/she is overwhelmed. Having less "help" forces the user to understand the process, but he/she is going to memorize it quicker and well. So in programming that means, not documenting creates the need the follow through the chain of functions, which in the end has two upsides: Better understanding, and the code gets looked at more, in case it's really bad and would benefit from a little rework :) I think documentation doesn't help anything. Yeah .. i'm a oppinionated f'er :) I'm probably wrong .. but I've yet to be conviced of it :)
@@SteveGriffith-Prof3ssorSt3v3 Oh .. i forgot the say the thing I wanted to answer to: The argument that my names might not make sens to other, kind of applies for docs as well. The way you describe a thing might complicate the matter. I've seen rather insane descriptions of simple functions. Mainly because of buzz-word-bingo issues :)
I'll agree that good code will have readable functions however I don't want to drill into every fn to see what /how it works. it's easier to write the fn name then hover over it to see what results I can expect. It also works best when you are in a team and someone else wrote that code.
I usually write enums like this /** @enum {!string} */ const Color = Object.freeze({ RED: "red", GREEN: "green", BLUE: "blue" }); Then I can use like TypeScript Color.RED, ... and I use jsdoc to be able to compile the app with closure compiler
Your channel has never failed me. Thanks a lot professor.
Thank you, Steve. You're a Gold Mine of Knowledge.
Awesome. Typescript without the pain
@11:54 you hover over the buildURL fn to show the comments that you placed. However you'll notice that your @return statement was blank. You have to remove the curly brackets to get it to show. There may be a better way to get it to show---> if there is PLEASE tell me.
well, I see that it's not showing in the bottom section BUT it does populate the top section. I was partially wrong. Is there a way to see the types in the bottom section too?
@@meisterunner I hadn't noticed the missing type in the message box. The type does appear when you mouse over the variable - let url.
If you add messages after the {URL}, those appear. You can write the datatype there too and it appears in the box.
It is an error in the parsing of the datatype by VSCode.
The curly braces are needed to identify the datatype. Without them it is viewed as just a message.
I would recommend that you go to the help menu and select "Report an Issue". Get credit for finding the bug.
I'm interested in this only because I'm making a public API and this is a mechanism that's easy to deliver documentation to developers and Copilot. I have seen some repositories where this was extremely overused with redundant and pointless comments, and even inaccurate comments. But it's a very, very good tool for highly used and well-maintained APIs.
Any tool can be poorly used. :)
Thanks Steve!
Thanks Steve
I've jet to see any code that got easier to navigate with comments. I don't put any comments in, I rather use names for variables and functions that are self explanatory. Since i'm more of functional programming kind of guy, the code tells you best what it's doing. This type of "documentation" looks insane to me. You can infer all the information just looking at the code.
Good code does indeed use an excellent naming convention. It will also follow a style guide that your team agrees on. It will also be well commented and documented.
This was a small contrived example of how to use JSDoc to help that process.
Comments always improve code, if not for you then for the people you work with. Your code and your names might make sense to you. Doesn't mean they make sense to everyone else.
@@SteveGriffith-Prof3ssorSt3v3 I can imagine that there is a scale of project, where this becomes useful. But to be honest, specially in JS development those are so rare that it doesn't make too much sense to conform to a paradigm in smaler scale projects in which they hinder more then help. So many younger programmers are way to hung up on best practices, preparing for a role they might never play. And even then, in large scale projects, documentation always lags behind to the extend that the product shipped with docs being only half ready, and never looked at ever again. Not saying that it's always useless, but very very often it is.
Another usecase for documentation is for libraries, but there, you want examples showing how to use the lib, but a list of methods and properties with potentially misleading descriptions. And you can always list methods and properties in the dev-console if you want to dig for things the docs didn't say (which is the case almost always). So yeah, the argument here is "docs would be cool, if they were complete, which they never are". Another argument i stole from UI design. The more you tell the user what to do, the more likely it is he/she is overwhelmed. Having less "help" forces the user to understand the process, but he/she is going to memorize it quicker and well. So in programming that means, not documenting creates the need the follow through the chain of functions, which in the end has two upsides: Better understanding, and the code gets looked at more, in case it's really bad and would benefit from a little rework :)
I think documentation doesn't help anything. Yeah .. i'm a oppinionated f'er :) I'm probably wrong .. but I've yet to be conviced of it :)
@@SteveGriffith-Prof3ssorSt3v3 Oh .. i forgot the say the thing I wanted to answer to: The argument that my names might not make sens to other, kind of applies for docs as well. The way you describe a thing might complicate the matter. I've seen rather insane descriptions of simple functions. Mainly because of buzz-word-bingo issues :)
@@herrbasan 😎
I'll agree that good code will have readable functions however I don't want to drill into every fn to see what /how it works. it's easier to write the fn name then hover over it to see what results I can expect. It also works best when you are in a team and someone else wrote that code.
Miller Angela Lopez Betty Harris Brian
If you are bothering to do jsdoc you might as WELL switch to typescript and get a better result with almost same amount of effort
No, avoiding a build step is way nicer. JavaScript does not need training wheels. JSDoc fills the void nicely without adding complexity to my deploys.
I usually write enums like this
/** @enum {!string} */
const Color = Object.freeze({
RED: "red",
GREEN: "green",
BLUE: "blue"
});
Then I can use like TypeScript
Color.RED, ...
and I use jsdoc to be able to compile the app with closure compiler