DEV Community

loading...

Discussion on: //TODO: Write a better comment

Collapse
adam_cyclones profile image
Adam Crockett

Consider the method:

sendNewsletterEmailOnSunday

Okay that's long but you won't need a comment, let's shorten it.

sendNewsEmailSun

Better but can we do more?

emailSunNews

It's getting harder to shorten and we are starting to loose context. This method could be mailing a customer on Sunday or maybe it's mailing the newspaper news on Sunday. So maybe a comment is needed... Or perhaps the problem is the method wasn't generic enough, bad design.

sendEmail(who, what, when)

That way the implementation is clear.

Other things that might help, decorator annotations, type safety and so on.

Collapse
adammc331 profile image
Adam McNeilly Author

Why did you feel the need to shorten the original method?

Collapse
adam_cyclones profile image
Adam Crockett

Peer pressure 😂

Collapse
adam_cyclones profile image
Adam Crockett

Okay seriously, as a developer I feel a compulsive need to express more with less, but not so much less that I can't express my meaning.
In the same way anti comment opinions didn't want to see novels because it gets in the way or perhaps insults thier intelligence, I think it's the former. But most of all I knew this was a bad method, because generic methods should always exist first then helpers can derive from them, with comments explaining what the base method does.

Thread Thread
adammc331 profile image
Adam McNeilly Author

I don't think it's a bad method. If you're only ever sending emails on Sunday, make a method that explains that. Making a generic (who, what, when) for only one use case is more complexity than you really need, IMHO. :) Premature optimization can be a bad thing.

Thread Thread
adam_cyclones profile image
Adam Crockett

Premature optimization doesn't exist in my book. Over engineering does. But if there are 7 days in a week and a client that might change thier mind. It doesn't hurt to keep it generic. That is where development point of view clashes because I do believe in future proofing but others don't, I get it and I'm cool with it, but I'm going to predict what is reasonable to predict, that's just me.

Thread Thread
adam_cyclones profile image
Adam Crockett

Somebody once told me "we don't know anything about anything. What we do know time will tell." So that is where my point of view comes from.

Thread Thread
adammc331 profile image
Adam McNeilly Author

Yeah, and sometimes it makes sense because like you said there are 7 days.

But whenever a project manager tells me "we might want to support this" I think really carefully about how likely that is, and whether it's worth over engineering now or just building for the project at hand.

Thread Thread
adam_cyclones profile image
Adam Crockett

Of course, we are talking about work, work, that means delivery takes precedence and with haste I agree. You get a feeling when something will take too long to explore, that feeling is my limit.

At home I just ignore that feeling and make my scripts do backflips around the internet whistling to the tune of yanky doodle. Now that's over engineering to be proud of.

Collapse
vinceramces profile image
Vince Ramces Oliveros

I prefer sendEmail(who: Person, what:string, when:Date) kind of thing. It's too verbose, but with clarity. But, we have our preferences in our code. Just, don't put dead code comments in that file.