DEV Community

Discussion on: To Comment Or Not To Comment?

 
codemouse92 profile image
Jason C. McDonald • 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.