This content originally appeared on DEV Community and was authored by Kevin Naidoo
I saw this comment in our API repo 😂, the code was even more confusing, which is probably why this dev had left such a bizarre comment.
To be honest, sometimes you go through those painful moments as a developer where you just want to break things, So I get it!
This got me thinking about commenting in general, and when and how we should comment in code.
Here's my take...
Comment with a ticket link
Sometimes you have to build in some weird business rules. Simply because, well that's what the suites want, it may not make any logical sense at the time and you know for sure that another dev or yourself down the line will look at this code and be so confused.
Instead of writing 20 lines of comments and polluting the code base, write a summary comment of one or two lines and then just link to JIRA or whatever project management tool you are using.
Avoid comments
You should not be explaining what a function, class, or block of code is doing. The developer working on the codebase should be able to read and make sense of it on their own.
Comments only make sense when you have to explain business logic that cannot be understood by just reading a block of code, in which case the comment should point to a wiki or company link where the developer can go read up on the business rules and context of this code.
Here's an example of a bad comment:
# Save a single review to the database and return its id
This is stating the obvious is it not?
# Skip the shipping flow here because this vertical
# pertains to digital products. Learn more here: https://short.ln/xyz
In the second comment, we indicate that this block of code is deviating from the norms in our codebase, therefore it's not a bug or error and the developer needs to be aware of this context when making changes.
Nobody maintains comments
Code changes with time, new features are added, bugs are fixed or blocks of code are even removed, however quite often developers forget to update the comments.
You then end up with tons of comments in the codebase that no longer make sense, this not only confuses developers but can also lead to some weird bugs because the new developer accepts the comment as truth, and follows the rules set out there, only to realize later down the line that comment is no longer valid.
Loose coupling is important
Quite often developers tend to leave comments because the process flow is way more complicated than it should be, you invoke a function, which calls another function, which calls another function and now you have to jump through 10 layers of code to get to the source of the problem.
In general, one should take the "blackbox approach", i.e. your functions should be as narrow-focused as possible and avoid relying too much on external dependencies, thus you avoid "wrappers" that simply pass parameters down the chain from one function to another.
So basically, stop using design patterns just because they are cool, every time you sit down to write a block of code, think of the simplest approach possible.
Only introduce complexity when required for performance and other logical reasons to save you from future pain or to maintain a consistent standard. An example would be building an "Adapter" class to connect to an external storage such as S3.
When you change your storage provider, you can then simply just swap out the adapter class without needing to change any code that talks to the storage backend.
Naming things is important
Sometimes we as developers struggle with this, however, you should make considerable effort to name functions, variables, and classes in a way that makes such a name easy to understand and summarizes its purpose effectively.
This content originally appeared on DEV Community and was authored by Kevin Naidoo
Kevin Naidoo | Sciencx (2024-07-18T13:25:17+00:00) 🤯 “// WTF 😔 I am so sorry” ~ Comment of the day.. Retrieved from https://www.scien.cx/2024/07/18/%f0%9f%a4%af-wtf-%f0%9f%98%94-i-am-so-sorry-comment-of-the-day/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.