Rob Pike on commnts

rob-pike-comments.md

Comments

A delicate matter, requiring taste and judgement. I tend to err on the side of eliminating comments, for several reasons. First, if the code is clear, and uses good type names and variable names, it should explain itself. Second, comments aren't checked by the compiler, so there is no guarantee they're right, especially after the code is modified. A misleading comment can be very confusing. Third, the issue of typography: comments clutter code.

Rob Pike, "Notes on Programming in C"

@james-se Pike's comment should be read in the context of senior developers who are well past being told that they need to use good function names; that's simply taken for granted.

IMO if your generics templating system forces you to use bad function names (like getData()) then get a better templating system. But even if you think it's ok to (have to) say getData(foo) because it's the only thing that foo contains, if you've chosen a good name for foo then it should still be self evident what the code does.

A bunch of bland generic names is unhelpful: thing = getdata(package) should be avoided in favour of tool = unwrap(widgetPackage), or even better, birthdayPresent = unwrap(widgetPackage).

It's a poor framework that precludes (more than a few) names from being fully descriptive.