The table of Contents seemed interesting and I was getting ready to buy the book until I discovered - the author has reserved between 1/3 and 1/4 of the book for chapters about writing comments.
~1/7 of the book by page count (about 30 pages if you tally the chapter lengths of nearly 200 pages), three chapters of twenty-two are dedicated to that topic (so not even 1/7th of the chapters). That seems reasonable since it's meant to be a broad book regarding software design and development. At least one page on comments is actually an answer to part of Clean Code, which is also relevant as the two books are in, roughly, the same subcategory of books on programming.
No, it doesn't. There are three chapters in that span that are on comments, but not all the chapters in that span are on comments. One is on naming things (Ch 14) and one is on modifying existing code (Ch 16). There are three chapters per the TOC that cover comments explicitly (versus where it may be touched on in other chapters): Ch 12 (pages 95-99), Ch 13 (101-120) and Ch 15 (131-135). That's a whopping 30 pages.
> You seem to consider it a negative to spend time on comments. Why?
Not just me. I've heard, read - here at HN, in the industry, blogs, co-workers, other books - the code should be self-explanatory. If it needs comments to explain then either the code author can't write good code or they are overly complicating it. Besides that, over time, comments get obsolete. We've to fight to get capacity to address tech debt. I don't see that time getting used in refreshing the comments
Short vars, long vars. Golfer, extender. Globalist and miniscoper. Class-splitter and method-lumper. Abstract composer and dead-on implementer. Typers, Dicters and Tuplers. I think I've seen them all. But so far I have not worked with a single person who'd not value a well-placed comment.
Can you point me to a codebase that does not use comments, as a model of how that looks in practice?
It’s a vocal but minority opinion, certainly a highly controversial one. As an easy example, it’s pretty difficult for code to self-document why a particular implementation approach was chosen. The book actually addresses the points you note.
