#CodeComments #ProgrammingTips #SoftwareDevelopment
Hey fellow coders! 👋
So, I’ve been diving into a big project lately and I’ve found myself pondering the use of comments in my code. Here are some of my thoughts:
– I’m on the fence about whether or not I should be commenting on every line of code, as it can get overwhelming and cluttered.
– I’m curious to know if in real-world projects, less commenting is actually more common because the code itself is clear and well-structured.
– Do you think too much commenting can actually hinder code readability? When should we decide to include a comment?
Personally, I’ve found that striking a balance between commenting and clean, concise code is key. Here’s a possible solution:
– Use comments sparingly for complex or crucial parts of your code that may not be immediately clear.
– Focus on writing self-explanatory code with clear variable and function names.
– Consider adding high-level explanations in your project’s README file for overall structure and functionality.
What are your thoughts and experiences with code comments? Let’s start a conversation and help each other level up our coding skills! 💻🚀
It’s late, so I’ll keep this short – the general conventional wisdom when it comes to comments in the code is this:
DO NOT use comments to explain WHAT the code does.
DO use comments to explain WHY the code does what it does.
BAD: /* Get the result from funcX and check it */
GOOD: /* funcX returns -1 when there is an error */
Teh bad comment tells you what the code is doing. That shold be obvious from jsut readong the code. Doesn’t explain why the result is important though.
The good comment on the other hand, explains WHY we get the result, and also why we check it for -1 and do something if it is.
Just started my first job a few months ago. One thing I noticed is there are no comments at all. We do have pretty good documentation, but not in the form of comments.
We don’t use comments except for projects where something like doxygen is mandatory.
Comments have to be maintained/updated and cause to much technical debt.
Especially in big projects where developer 1 creates a comment, developer 2 updates the code sometime in the future, but didn’t update the comment, 3,4 and 5 did the same, developer 6 sees that the comment isn’t matching with the code, and nobody now knows why dev 1 put a comment there and he is long gone.
Oh and the worst of all, // TODO: , sure fine for your own personal projects, but in a Professional setting or do it now (before submitting the pull request), or put it on the backlog.
If you’re a beginner comment things you need to remember. You’re not working on a professional project and so the audience for the comment is you and the rules are different.
Generally comments should convey information to the reader that is not obvious in code, and you should aim to minimise them as they need to be maintained and get out of date quickly.
A bad comment would be something like “this function saves a user into the database”, just call the function SaveUser() and you remove the need for a comment.
Good comments would be something like “this timeout is set to 27 seconds because anything more would cause issues downstream in x service, check y before increasing” – while this should also be in documentation it’s a final safety check that someone will see before making an edit.
You should also use comments to explain complexities in your code if necessary. Like “this formula does x, we do this to calculate y, further info is found at <link>” but only where you can’t make it clear from the naming of variables and functions.
Realistically in a real world situation you should keep comments to only where they are really needed and if you feel you need a lot you probably need to refactor your code for better readability.
Wanting to comment everything can be a sign that you’re trying to do too much with one method, or that you’re not naming things correctly.
Try writing the comment, and then look at it and think about whether that comment is redundant. If you feel the code is needed because the logic is complex, maybe that logic would be better off extracted to a method or local function that describes what it’s doing.
That said I’m also a junior and I admit sometimes patterns just aren’t as obvious to me and English would be nicer, but that’ll come with time.
Write your code so it doesn’t need comments to explain it. Add comments when you can’t.
Let me give you an example of some real-world comments I have in my code base:
/* IE 7 has a rendering bug where this translate does not apply properly, but we can kick IE 7 elements into a different rendering path by saying zoom: 1. Redundant, but required. */
/* Although this file claims to be a CSV (comma separated file), the first two lines are actually meta data, so we exclude them.*/
Note: This comment was removed later on by removing the first two lines from the file off into their own own values and then starting the loop at the new cursor position, which required zero code comments.
/* Although the documentation for this API says that it sends all values as proper types, it is lying. The numbers are likely to come in quoted, so make sure we do proper conversion here, even though it appears un-needed. */
This was followed by calls to functions like: “ensureValueIsNumber” and “ensureValueIsBoolean”
/* The remote system must be using floats to calculate these values. We are using decimal numbers with no loss of precision. If anything is within a penny rounding problem, just add a slight discount to the invoice to make the two totals equal. */
Good question! IMO, comments should explain why, not what the code does.
Yeah generally in a code base you’ll find that there’s less commentary. Comments are useful when you anticipate someone will go “hey, that’s odd.”
Comments should be anticipatory (IMO), or used tactfully to describe why something is, and if it’s subject to a particular change later on.
For example:
“The API call is not wrapped, this upgrade will be done in XYZ”
But again, it’s anticipating that someone looking at your code will be like “huh, why?”
I use comments to remind myself why the fuck I did what I did.
Like, why am I checking if the function returns 0 instead of if it returns 1? Well, because for some reason the person that made the function decided to use 0 for okay and 1 for error.
Which is not how I usually do things, so I commented it so I can quickly understand next time
I like the take [“Comments are there to explain code that can’t explain itself.”.](https://www.youtube.com/watch?v=g51HPBFCOwc)