The "Reference" says "Comments in Rust code follow the general C++ style of line (//) and block (/* ... */) comment forms." The Reference, however, "tends to be out of date".
At least as far as I've been able to find (perhaps I've missed it), The Book does not mention C/C++-style block comments in either version. Blandy's book doesn't mention them either. But I've tested the use of them and they seem to work.
What is the truth here? /* ... */ comments are useful when porting C code to Rust. But the different messages from different documents give me pause. Are block comments officially supported?
Block code comments are officially supported, AFAIK. There was some discussion a while back about potentially deprecating block doc comments, but I don't know where that netted out. I would be very surprised if block code comments became unsupported. But, this is by no means an authoritative answer.
They are. I use them way more than line comments. Even better, they nest.
I suspect the reason they're rarely mentioned is that certain people on the Rust core team seem to really hate them. I guess maybe a block comment ran over their dog when they were a child, or something, I dunno.
Thanks for the responses. I would like hear from the primary documentation people about this point, so Vitaly's suggestion that Steve Klabnik weigh in is a good one. If we don't hear from him here, I'll file an issue on the github repository.
The book does not mention them because they’re not considered idiomatic. The book’s primary job is to teach you Rust, not cover every last thing in the language.
The reference is “out of date” in that some stuff is missing, but everything that is there should be accurate.
I’m not a fan of being dictated too either. In the Golang community they actually try to dictate where you must write your command line argument parsing code in your app design for it to be idiomatic. What that has to do with engineering a programming language I’ll never know.
It's likely to do with consistency. If command-line parsing code is always located in the same place, it's easy for people coming on to a project to find the code, and to know where and how they should structure changes. Familiarity and consistency makes collaboration easier. It's the same with formatting styles. I mean, sure, you can understand written English when you remove most of the vowels and replace words with colloquialisms, but it involves a lot more effort on the part of the reader. It's the same thing: reducing the burden on others.
Of course, the flip side of that coin is in stamping out dissent and making sure everything is done correctly, with "correctly" being the way you already do it, because of course you're doing it right. Anyone doing it differently is just causing problems, making things harder for the whole. Of course they should be stamped out; it's for the greater good. Disharmony is bad.
As the saying goes: the road to hell is paved with good intentions. That doesn't mean establishing and encouraging such conventions is bad; there absolutely are positives to be had. I think communities just have to be careful that they aren't going too far.
Which is why we, the shadow council of Rust, allow people to continue using single-line comments, despite them being wrong and deviant. Because we're just that magnanimous.
Regarding the command-line parsing code, perhaps the Golang team should have just passed them in to main() instead of having functions you can call from anywhere in your code to access them. They're clearly already stored in memory, so placing them in global immutable data structure on app launch in case a condition may arise in your app in which you may actually need to read one of the values, is hardly much different from reading the value directly using a official API when you need it. I've working in enough companies to know that most of them do things their way regardless of open-source community conventions.
I agree with you on consistency, which is why it seems a bit contradictory to have the compiler allow block comments but then try to stop people from using them. After 40-50 years? of their pervasive use, if they were the cause of countless issues we'd know about it by now.
I can't tell if your serious or joking about single-line comments comment. Why do you think they are wrong and deviant?
Not explicitly mentioning them isn't quite the same thing as actively trying to stop their use. I mean, that would involve something ridiculous like introducing an RFC to strip them from the language entir...
You know what? Nevermind.
*boggle*
... in what way could I possibly have not been joking?
If making a statement that would probably only be considered seriously in the context of people actually living through the plot of 1984, but also suggesting some kind of shadow government ruling Rust (which would be ridiculous even before you consider that Rust is an open-source project largely managed via public GitHub issues) that would likely not be taken seriously even in Deus Ex or The X-Files... wasn't enough to clue you into the fact that I was joking, ... then I really don't know what to say.
I was referring to Steve’s statement above “The book does not mention them because they’re not considered idiomatic.“, when I said try to stop people from using them.
I’m new here. Maybe that’s how the team refer to themselves, I don’t know. Plus sarcasm from a stranger on the internet. There are people who believe that code should be self-documenting. I’ve worked with people like that, who would freak out at a single line comment, so before you mock me realise that not everyone lives in your bubble.
Sorry, I'm very confused about a few of the things you're saying here. If this comment is truly at me:
I do not think they are "wrong and deviant." Nor am I trying to stop anyone from using them. They're in the language, feel free to use them if you'd like. But as I said above, the book does not cover the entire language. Its job is not to be comprehensive; that's the reference's job. Its job is to teach you Rust. As such, it follows the conventions that the community has developed over the years. Similarly, the compiler will let you write functions like this:
fn foo()
{
}
but that's not the convention; the convention is
fn foo() {
}
and so that's how the book shows off functions. It's the exact same thing with comments.
I do think it's nice for consistency (even though I prefer block comments and textwidth 80) but it might be better if the book is consistent which probably might be good for a mention that such things exist. IIRC there was block comments back then when I read it.
Alright, that's a reasonable point. That said, every "shadow council" I've ever come across has been either part of a conspiracy theory, or was fictional. And always, always evil. Which is why I used the term: a shadow council would never announce itself as such. Still, it's plausible it's done tongue-in-cheek, so fair enough.
I find it hard to believe that anyone would judge someone to be of a lesser moral quality for using single line comments, either because they believe comments should be unnecessary, or because they believe you should use block comments instead. Disagreeing that they're the best approach, certainly, but using the same word as you would for people who have sex with animals?
If people like that actually do exist, I think they're entirely appropriate targets for ridicule, and shouldn't be taken seriously.
Also, I wasn't trying to mock you, I'm trying to get across how much I don't understand where you're coming from. I mean, I chose something I couldn't conceive of anyone possibly taking seriously, only for you to take it seriously. I can entirely understand you never having come across the trope of an evil shadow council (insofar as not recognising the name being used), but the whole "using single-line comments = deviant" being reasonable just... my brain refuses to accept that.
Well, from a newbie point of view, I initially find it strange that there isn't any mention of block comments. Frankly, I didn't realized you can use the /* */ syntax until I came across this thread.
I agree with steve that its not the book's job to be a language reference, but I feel that block comments is the basic thing you expect once you start discussing about comments. My 2 cents, just mention block comments in the book and tell its not idiomatic to use and leave it up to the user.
I've never read a programming language book that didn't address the comment syntax in the introductory chapter. It's often the first thing that's mentioned after hello world.
Well, I can feel you. Its just the way all the programming books works I guess and most of us are used to it. But, generally its a personal taste and preference. Some people would like to make the complexity of topics a little gradual and some would like to jump in and get to the core of it and cover the simpler details later. I won't fret about the order much as long as its mentioned somewhere!
recommend but don't require line comments, allow block comments if people want; fix rustfmt to not mangle either kind of comment (move but don't change); possibly in the future allow rustfmt to reformat doc comments only (not non-doc comments).
So, in general, we are biased to not using block comments, but we are positive towards people using block comments anyways.
I'm fine with the book using a particular style for all the reasons @steveklabnik mentions above.
Also, as there was an accessibility angle in the debate, I also want to note that "///" comments are more accessible to some people and multiline to others, or the other way around, depending on method of display. More here.
Edit: previous wording made it seem that "///" is preferably from the accessibility perspective, while the point is that it's not clear cut.
I keep forgetting this exists but there is always the reference documentation regarding comments that is explicit. It's not an official language spec yet, but at least it's written down.
