book: mention the existence of block comments in passing #28411
Conversation
While the style guide does say to avoid block comments (https://doc.rust-lang.org/stable/style/style/comments.html#avoid-block-comments.), some might argue that readers of the book should still be briefly exposed to the fact that they exist, in order to avoid surprise or confusion should one happen to encounter them, or perhaps to make it easier to edit Rust code in an impoverished editing environment lacking an appropriate comment-region command?
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @steveklabnik (or someone else) soon. If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes. Please see the contribution instructions for more information. |
|
I specifically left them out of the book, since they're not considered good style. They're in the reference, though. Thanks, but this was deliberate. |
|
I also think they should at least be mentioned in the docs, with the comment that they are considered bad style and should be avoided ( for whatever reason... ). Block comments are really the only viable way to quickly comment out a block of code, if the editor/ide does not support other methods. I was growing really frustrated by that, until I just tried '/* */'. |
While the style guide does say to avoid block comments, they should perhaps be briefly mentioned in the "Comments" section of the book, to avoid leaving readers with the false belief that they don't exist.
r? @steveklabnik