4 ms·

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 fo

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.

Jtsummers 4y ago
~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.
- mandeepj 4y ago
  > ~1/7 of the book by page count (about 30 pages if you tally the chapter lengths of nearly 200 pages), Comments chapters start from Page #91 to 142, totals to 52. Total pages - 175; not counting index and summary pages. 1/4 of 175 = 43.75 1/3 of 175 = 58.33
  - Jtsummers 4y ago
    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.
lolc 4y ago
You seem to consider it a negative to spend time on comments. Why?
- mandeepj 4y ago
  > 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
  - layer8 4y ago
    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.
  - lolc 4y ago
    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?
    - layer8 4y ago
      I believe I understand most of those, but what’s a dead-on implementer?
      - lolc 4y ago
        Not looking beyond the next line to solve a task.
    - mandeepj 4y ago
      > Can you point me to a codebase that does not use comments, as a model of how that looks in practice? Once we actively encourage “comments”, this is what we get. It was totally unnecessary - https://github.com/nopSolutions/nopCommerce/blob/develop/src/Presentation/Nop.Web.Framework/WebWorkContext.cs#L204 https://github.com/nopSolutions/nopCommerce/blob/develop/src... I welcome this type of comments which does not say the obvious and goes beyond what the code in front of you can’t state - "// If every heap's gen2 or gen3 size is less than this threshold we will do a blocking GC." https://raw.githubusercontent.com/dotnet/runtime/main/src/coreclr/gc/gc.cpp https://raw.githubusercontent.com/dotnet/runtime/main/src/co...

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.

Jtsummers 4y ago

~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.

mandeepj 4y ago
> ~1/7 of the book by page count (about 30 pages if you tally the chapter lengths of nearly 200 pages), Comments chapters start from Page #91 to 142, totals to 52. Total pages - 175; not counting index and summary pages. 1/4 of 175 = 43.75 1/3 of 175 = 58.33
- Jtsummers 4y ago
  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.

lolc 4y ago

You seem to consider it a negative to spend time on comments. Why?

mandeepj 4y ago
> 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
- layer8 4y ago
  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.
- lolc 4y ago
  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?
  - layer8 4y ago
    I believe I understand most of those, but what’s a dead-on implementer?
    - lolc 4y ago
      Not looking beyond the next line to solve a task.
  - mandeepj 4y ago
    > Can you point me to a codebase that does not use comments, as a model of how that looks in practice? Once we actively encourage “comments”, this is what we get. It was totally unnecessary - https://github.com/nopSolutions/nopCommerce/blob/develop/src/Presentation/Nop.Web.Framework/WebWorkContext.cs#L204 https://github.com/nopSolutions/nopCommerce/blob/develop/src... I welcome this type of comments which does not say the obvious and goes beyond what the code in front of you can’t state - "// If every heap's gen2 or gen3 size is less than this threshold we will do a blocking GC." https://raw.githubusercontent.com/dotnet/runtime/main/src/coreclr/gc/gc.cpp https://raw.githubusercontent.com/dotnet/runtime/main/src/co...