But in the process you see that the “more obvious” solution is actually lacking.
#Doxygen node.js code
You (or your colleague) open the code written some time ago, and see that it’s “suboptimal”.Without such comments the following situation is possible:
If there are many ways to solve the task, why this one? Especially when it’s not the most obvious one. Why is the task solved exactly this way? The code gives no answer. But what’s not written may be even more important to understand what’s going on. You can read more information about JSDoc at. Such comments allow us to understand the purpose of the function and use it the right way without looking in its code.īy the way, many editors like WebStorm can understand them as well and use them to provide autocomplete and some automatic code-checking.Īlso, there are tools like JSDoc 3 that can generate HTML-documentation from the comments. Document function parameters and usage There’s a special syntax JSDoc to document a function: usage, parameters, returned value. There’s a special language UML to build high-level architecture diagrams explaining the code. Which comments are good? Describe the architecture Provide a high-level overview of components, how they interact, what’s the control flow in various situations… In short – the bird’s eye view of the code. So, explanatory comments are usually bad.
But generally we should try to keep the code simple and self-descriptive. And there are smart “tweaks” for purposes of optimization. In reality, we can’t totally avoid “explanatory” comments. It’s clear what every function does, what it takes and what it returns. And also the code structure is better when split. Once again, functions themselves tell what’s going on.
0 kommentar(er)
