DEV Community

loading...

Discussion on: Keeping Your Code Simple

Collapse
tiffany profile image
Tiffany White Author

Disagree about comments. Comments should tell the reader why not how.

The reason there are comments in the first example was because I was applying to a bootcamp and wanted to explain my process to the admissions office.

Collapse
pawda profile image
Memoria • Edited

Fair enough, just keep in mind that documentation is different from comments.

I would just like to add something you might be interested in.
If you wanted your function "longestString" to be available outside of its package as a library function for example, you would want to comment using jsdoc.

More than it allows you to generate an html doc form your code, your IDE knows about jsdoc and can generate friendly popup as you try to use this function.
Have a look at the difference:

Without jsdoc
Without jsdoc

With jsdoc
With jsdoc

To finish, while being old (but definitely not irrelevant) and not JavaScript specific, I invite you to read Clean Code: A Handbook of Agile Software Craftsmanship from Robert C. Martin (Uncle Bob).

Cheers !

Thread Thread
lowla profile image
Laureline Paris

You might want to change the order of your picture ( first picture showing actully the ' without jsdoc ' and the second showing the ' with jsdoc '

Thread Thread
pawda profile image
Memoria

Thanks for pointing this out :)!