DEV Community

loading...

Discussion on: To Comment Or Not To Comment?

Collapse
codemouse92 profile image
Jason C. McDonald Author • Edited

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.

Collapse
flolenz profile image
Florian Lenz • Edited

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++.

Thread Thread
codemouse92 profile image
Jason C. McDonald Author • Edited

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 need extract_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 get one_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.

Forem Open with the Forem app