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"
Last active
August 5, 2024 17:04
-
-
Save jarek-przygodzki/fc948cf4671edd808d31b89289a0f78f to your computer and use it in GitHub Desktop.
Rob Pike on commnts
@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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
"First, if the code is clear, and uses good type names and variable names, it should explain itself" Not true on all cases. Inevitably, generics and other things lead to function calls like "getData()" that just are not clear what they do. This is where a nice clean one-liner comment makes sense, especially when the code is intended to be shared and maintained by hundreds of developers at a company.