3 ms·
I went back to check and this is what the book says, verbatim: "Every function in this program was just two, or three, or four lines long. Each was transparent
by ncann 3y ago
I went back to check and this is what the book says, verbatim:
"Every function in this program was just two, or three, or four lines long. Each was transparently obvious. Each told a story. And each led you to the next in a compelling order. That’s how short your functions should be!"
So I think it's fair to say the book advocates for functions 2-4 lines long.
And about comments, from the book:
"So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code. Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your ability of expression"
"Some comments are necessary or beneficial. We’ll look at a few that I consider worthy of the bits they consume. Keep in mind, however, that the only truly good comment is the comment you found a way not to write."
With opinionated sentences like these, it's not hard to see how one would read the book and adopt a "no comment" mindset.
- xorcist 3y agoIt also completely misses the point of why comments are useful. "Store user.age in age variable", is a useless comment which is indeed better expressed with clear code. "Store user age in struct because when xyz() iterates over this it has no way to access the user object" is useful because it tells us why something is done, where it is used, and why the obvious solution isn't right.
- PH95VuimJjqBqy 3y agoI fought and lost this battle with one of our teams. The tech lead insisted they use XML comments (Visual Studio) for everything. ///<Summary> ///Represents the User ///</Summary> public class User { ///<Summary> ///Users Age //</Summary> public int Age {get;set;} ///<Summary> ///Users First Name //</Summary> public string FirstName {get;set;} } ad nauseum. Here's the thing. Swagger (.net) can pick up the XML file generated from these comments and it gives developers the ability to add more information to the Open API Spec file (swagger generates a UI off of it). So it has a legitimate use, but if you don't have anything than to repeat what the damned code already says, it's harmful to the readability of the codebase.