Commenting. It's one of the more controversial points of code style. There's no lack of opinions on the topic, but there's very little uncertainty ...
For further actions, you may consider blocking this person and/or reporting abuse
There's the old saw that you should "code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live". That is, don't make him angry by writing really clever code that he can't understand.
Well, comments are part of code. So don't comment in such a way as to piss him off either. So don't assume he's an idiot, that will just annoy him, and don't assume he's really clever and miss out important information that he will need, and for which he will be willing to kneecap your children.
Alternatively, if you find it hard to get into the mindset of a violent psychopath, comment for an audience of yourself on the day you were first exposed to the project you're working on.
I comment for (1) the day when I'll come to work with a foggy brain and have to check my code to debug or reverse-benchmark something. (2) that he/she will cover for me
Very good way of thinking about it.
Replace comments by functions' names and Id be on the same page.
What do you suggest? 80?
The exact line length really depends on things like language, editor, etc. Modern screens afford us more room to work with than back when "80" was the standard, even if your editor is only taking up half the window. I find 120 is usually good to start.
Also, as I said in the article, don't confuse the purpose of self-commenting code (function names being part of that) with comments. They work together, but one doesn't replace the other. Attempting to pack that much information just into function names results in those 60+-character atrocities Facebook source code is infamous for, and at that point, readability went out the window.
Well, if you really need 60+ characters to describe the intent of your function, you should try to split it up. Yes, sometimes it is not possible, and THIS is one of the rare cases where I would use a comment.
Functions like "write(all_lines, output_file)) or extract_email(csv_contact_book) have all the advantages of commenting the intent, without the disadvantages. Even in C++.
I don't know that those fully imply their intent. Is your
write()just writing out the text to a text-based file? (That might be one you could get away with...but then, you almost definitely won't be writing this function yourself anyway.)More unclear, are you extracting a single email address from
csv_contact_book, or are there criteria? Are you extracting a list of all the emails, or just those that match some specified or arbitrary filter? All of that is unstated and assumed here, and explicit is always better than implicit. You'd needextract_all_emails()just to get around that part, and already we're getting longer function names. Add two or three more criteria to the functionality - as production code almost certainly would - and you getone_of_those_horrendously_long_function_names_just_shoot_me_now().Self-commenting code like this is good, even vital, but in my experience, it's rarely sufficient to describe the whole intent. It looks obvious to you, since you just wrote the function (or made up the examples), but not necessarily to another reader/coder/future self. And of course, real code is always a lot more snarly than comfy little examples. :)
This is why I recommend writing the intent-comment anyway. If someone else reading your code for the first time can objectively say "this comment is redundant", then and only then is it safe to refactor it out. One cannot reliably tell what's obvious and what isn't in their own fresh code.
As to the self-commenting code, do it. Never send a comment to do a name's job. But conversely, don't send a name to do a comment's job. The name is the WHAT, the comment is the WHY. Neither is qualified to compensate for the lack of the other.
And what people seems to forget is: people don't like to write more than necessary. So if someone write a comment s(he) need it or thinks s(he) will, nobody do it to do harm. I like commenting a lot and before commit I check the comments and start trying to remove them, usually shows me that a variable have the wrong name, something is doing something it shouldn't, some language concept is not clear enough to me yet, etc. After this cleanup I naturally endup with very few if any comments and those where the ones I couldn't explain with the code, maybe because I don't understand something yet but all you can do is the best you can do. Being perfect would be very boring.
Great article, fully agree with it. I am sixty now, 40 years xperience. Read lots and lots of programs. None had good comments. I myself do it as a second nature. Should be like that with every developer. Problem is lots of developers are good in math but bad in language. A guy asked Bill Gates: do you need to be good in math to be a great developer. Silence for a while...then the aswer was no!
As a developer who's always looking for ways to improve both my code and communication practices, I found this article on code comments insightful. It strikes a balance between explaining the importance of meaningful comments without cluttering the codebase. In a similar vein, tools like SalesBlink’s email cadence software enhance the clarity and efficiency of sales communications. Just as good comments can streamline understanding and maintenance of code, SalesBlink ensures that each email in a sequence is purposeful and strategic, ultimately driving better engagement and conversions.
Thank you very much. That was very helpful.