Re:Writing system software: code comments
by apo on Sunday October 07, 2018 @01:43PM
(#18161736)
I'll take well-named variables, functions, and classes over code comments any day.
It's a chore and and half to plow through code in which the author has, for whatever misguided reasons, shortened variable names to inscrutable abbreviations, acronyms, and single letter head-scratchers.
Context-switching between comments and code may be easy for the author, but isn't good for the reader.
More often than not, the short-variable tendency points to an even worse problem: the author hasn't though very deeply about the software at a high level and therefore hasn't developed a good vocabulary or conceptual framework around the problem space.
Re:Writing system software: code comments
by Drdrdrq on Sunday October 07, 2018 @04:31PM
(#18162467)
This! I don't mind comments, but thinking they can replace good naming discipline is misguided imho. I prefer less comments, and only those that explain intent. (+API docs of course)
It's a chore and and half to plow through code in which the author has, for whatever misguided reasons, shortened variable names to inscrutable abbreviations, acronyms, and single letter head-scratchers.
Context-switching between comments and code may be easy for the author, but isn't good for the reader.
More often than not, the short-variable tendency points to an even worse problem: the author hasn't though very deeply about the software at a high level and therefore hasn't developed a good vocabulary or conceptual framework around the problem space.