For what it's worth, I absolutely love reading this sort of spanning descriptive comments. It makes the code that much more interesting and gives it a healthy dash of personality.
I used to work with a guy who'd have header files start with pagefuls of comments with ASCII diagrams, book references, complete design rationale and what not, only to follow with just a handful of rather terse declarations, which still would be immediately clear thanks to the preceding narrative. That was so damn beautiful.
For what it's worth, I absolutely love reading this sort of spanning descriptive comments. It makes the code that much more interesting and gives it a healthy dash of personality.
I used to work with a guy who'd have header files start with pagefuls of comments with ASCII diagrams, book references, complete design rationale and what not, only to follow with just a handful of rather terse declarations, which still would be immediately clear thanks to the preceding narrative. That was so damn beautiful.
[0] https://github.com/munificent/wren/blob/46c1ba92492e9257aba6...