So, we’ve looked at the good and the bad, but what about the ugly? Here’s a simple example in JavaScript: /* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value) The Ugly And when you do, the comment should specify what solution you tried and why you decided against it. But you SHOULD leave a comment warning others not to pursue some seemingly obvious “better solution,” if you’ve already tried and rejected it. The following mock-comment captures this scenario perfectly: /**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/Īgain, the above is more about being funny than being helpful. In those cases, it’s best to save everyone the time and embarrassment and leave a comment. Sometimes that other coder is your future self. In those scenarios it is almost inevitable that some other coder will come around thinking they are much smarter than you are and start messing with the code, only to discover that your way was the best way all along. There are also times when - after a lot of thought and experimentation - it turns out that the seemingly naive solution to a problem is actually the best. * * Replaces with spaces * the braces in cases * where braces in places * cause stasis.**/ $str = str_replace(array("\ Here’s an example of a bad - though very entertaining - clarification comment. You should strive to remove clarification comments and simplify the code instead because, “good code is self-documenting.” It tells you that your code is too complex. Often, a clarification comment is a code smell. Clarification commentsĬlarification comments are intended for anyone (including your future self) who may need to maintain, refactor, or extend your code. Collapsing comments with code folding in Visual Studio Code. The good news is that most code editors support “code folding” which allows us to collapse the comments so we can focus on the code. The downside of these kinds of comments is that they can make your code very “noisy” and harder to read for anyone who is actively involved in maintaining it. Some popular and well supported standards and tools include JSDoc for JavaScript, DocFx for dotNet, and JavaDoc for Java. If you write documentation comments you should ensure that they follow a consistent standard and that they are easily distinguishable from any inline clarification comments you may also want to add. If you compare these comments to their online documentation, you’ll see it’s an exact match. Here’s an example of a documentation comment from a popular JavaScript library called Lodash. A good strategy to mitigate this is to embed the documentation directly into the code and then use a tool to extract it. The further removed from the source code your API documentation is, the more likely it is to become outdated or inaccurate over time. If you are building a library or framework that other developers will use, you need some form of API documentation. Documentation Commentsĭocumentation comments are intended for anyone who is likely to consume your source code, but not likely to read through it. I call them documentation comments and clarification comments. In this article we’ll look at the good, the bad, and the ugly when it comes to commenting your code.įor starters, there are really two different types of code comments. But this truth has been so abused that most people who utter the phrase have no idea what it really means.ĭoes it mean you should never comment your code? No. In 20+ years of writing code for a living, this is the one phrase I’ve heard the most.Īnd like many clichés, it has a kernel of truth to it. Stop me if you’ve heard this one before… “Good code is self-documenting.”
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |