These bad comment practices are a direct path to spiralling tech debt and declining code quality. When TODOs make it to `main`, you end up with a never-ending, invisible backlog which isn’t actionable. TODOs are definitely better than having a list on the side, because they have context. They are great for temporarily dumping thoughts so you can focus on what you’re doing. Or, try Stepsize to track and manage tech debt from your code editor. If you’re not already using a tool for this, try Jira or Linear for app-based issue tracking. This avoids accumulating serious tech debt that can be hard to pay back. Here’s an important point – if engineers are writing tonnes of comments to explain complexity, that could be a code smell.Īn engineering practice your team should adopt is consistently documenting unnecessarily complex code as issues. (This is how teams get themselves buried under heaps of tech debt without even knowing it.) When it ought to be ticketed as an issue.When the intent of the function is obvious.If somebody sees a comment, they’ll know it’s incisive and valuable. A comment would save readers from working it out.įewer comments often mean more readable code. When context is missing, for example, using code from another repo or a packageįor example, it’s unclear whether the `start` and an `end` parameters are inclusive or exclusive.To add details to increase precision, such as units, inclusivity and exclusivity or the treatment of null values.Where there’s unavoidable complexity in your code.These harm code quality and velocity, particularly when it happens routinely. When we misunderstand code, it’s possible to introduce inefficiency, unnecessary complexity and bugs. Well-placed comments save development time and prevent engineers from misunderstanding the purpose or context of a code snippet. The last thing your team needs are comments that explain things which are already obvious by glancing at the code! These explain code in context, wherever they are needed. Any features of the module which can’t be understood at a glance.These describe the purpose of classes, functions and methods. The first type are module-level comments. There are two primary types of contextual comments. Contextual commentsĬontextual comments are used to describe any purpose, intent or feature of code that isn’t obvious by looking at it. Types of comments (and when to use them) 1. But the bottom line is that various kinds of information simply can’t be represented in code. As John Ousterhout says, this is a delicious myth.Ĭomments can indeed be used to plaster over poor or unclear code. Some say that if a piece of code is written well, we can do away with comments altogether because that code’s purpose will be obvious. Talk about when not to write them (and what to do instead!).Cover some code commenting best practices.Discuss when and how to write code comments.Explain what types of comments there are.In this complete guide to writing meaningful code comments, we’ll: Combined with the code quality nosedive and velocity issues they cause, poor commenting leads to mounting problems, from huge learning curves for new engineers to invisible backlogs of tech debt. This makes them a poor alternative for proper documentation or issue tracking. They’re not easily searchable or visible beyond looking at the code. After all, code comments are an unstructured way of storing information. On the other hand, when we don’t embrace good practices, code comments can have the opposite effect. The most obvious and immediate benefit of writing good comments is that they make code easier for others to understand.īut when we nail our code commenting best practices (which include when to and when not to write comments), we can unlock even more impactful, long-lasting benefits like: Been there? If you’re anything like most engineers, it’s safe to say this happens to you a lot.
0 Comments
Leave a Reply. |