At my new job, they are very particular about coding standards, and in code reviews I'll be given a comment if my code doesn't follow their standards.

I think think this great actually, because their standards are clear, and all of the standards make for better code and more readable/maintainable code.

But there's one standard which confuses me, and it seems counter intuitive, so I keep messing it up. Can someone explain to me the reason that someone might adopt such a coding standard, what the psychological reason might be for it?



The standard is:

- If you have an HTML comment for a class/method/property using the triple slash, your sentence MUST end with a period.

- If you have an inline comment for miscellaneous body code, using the double slash, then your sentence MUST NOT end with a period.

I keep messing this up because I like to type proper English sentences (well, as proper as we can get in America anyway). If there is a way I could wrap my brain around WHY, then maybe I'd mess it up less often. Any ideas?

Without any parsing (I haven't programmed in ages), perhaps it's just an arbitrary internal check bit?

-jk

Maybe they have an extract program that extracts the /// and or // comments and the period is needed for /// cases. We had a documentation library program that worked in a similar fashion. You had structure the comments just right or they would not be picked up correctly by the library program.

"Because that's how we've always done it!"

tanstaafl.

This is my guess too, something like Doxygen in use.

I hadn't really thought about it until you mentioned, but it turns out I abide by those rules too. Perhaps the way to think about it is that single-line comments are like newspaper headlines, and aren't expected to be full sentences, whereas doc-comments (or Doxygen comments or whatever) are more like the text of the newspaper article, so they're properly punctuated with full stops like running text. The usual pattern for both Doxygen comments and Git commit messages, is that the first line is a one-line "headline" summary, with no full stop, and then if any more detail is needed there's a blank line followed by a paragraph of real sentences with full stops.

Peter

Have you tried asking them why rather than us?

My guess would be some kind of parser like Doxygen also.

Edit: Not a fan of that first indent though.

I agree -- that would explain the MUST, as those comments are extracted for external documentation (otherwise, why would you write them in HTML? But it doesn't explain why internal comments MUST NOT have a full stop. If you're writing comments in full sentences, they should be punctuated as full sentences (IMO). And what if you have a more complex internal comment?

Do you leave the full stop off of the last sentence? Or all of the sentences? What if your comment is written in the form of a question? Can you put a question mark? Does the rule pertain only to the full stop, or is all punctuation verboten?

Maybe it's just the sample Tony provided, but it feels like this sort of coding standard policy shows up when you only have short (and pointless) comments. IMO, comments such as those in the sample shouldn't even be allowed in the code, and the coding standard would address the value of comments (not just the style). But that's an argument for another thread...

If you're not familiar with Visual Studio, that's a particular thing in Visual Studio. It's not only for a third party dox extractor (though it's used for that too), it's mainly useful for tooltips and IntelliSense help while you're coding.

For example, you're used to to IDEs which, when you type the name of a function, will automatically guide you through all the parameters to that function, right? Well, if you add those HTML comments in a particular format to your classes and functions in a Visual Studio project, then you get the same thing for your code's own internal functions. The format is larger and more complicated than what I provided in the oversimplified example. Here's a post about it: https://msdn.microsoft.com/en-us/magazine/dd722812.aspx

Regarding dox extractors like Doxygen... we're not documenting our code with any sort of automatic dox extractors that I know of. The code I'm talking about is all internal and doesn't have any formatted reference material (other than the self-referential stuff in the IDE as described above). Perhaps they're just making sure that if we ever DID use a third party dox extractor, then our code would be ready for it. Which is fine, but then, why the weird thing about no periods on inline comments? That's not part of any dox extractor that I know of.



Exactly, that's the thing that I'm not understanding and which trips me up. The fact that my company requires it is not in question, but since I know it's not a requirement for dox extraction, then, why deliberately subvert the English language like that? I was thinking that there's possibly some psychological reason for it, such as, I dunno, maybe trying to make the code flow more readable inside functions or something? I can't fathom it, but I'm wondering if there's some weird "school of thought" which espouses that style, and what its justification is, if it exists. Like, hungarian notation. That's got a whole thing behind it, it's there for a reason. I thought maybe this did too.

Okay, okay, that's starting to make sense. You don't put periods at the end of a headline. That, that right there, is indeed an actual English rule that I can understand. If we were extracting out to dox, then that would mean something.

However, that's not what our coding standard says. Our coding standard just says "inline comments, no period. Tripleslash comments at the tops of methods and classes, put the period."

I wonder if the coding standard here came from something like that, but then the real details got diluted, and when it finally got typed into our coding standards, the original meaning was lost? Sort of like an E Plebneesta of coding standards?

Larry Wall would be very disappointed in your lack of ability to self-express

I hope every facet of working for your company isn't this much of a PITA. I totally understand having standards, but dictating punctuation in comments (unless there's a good reason) is a bit over the top IMHO.

The company has been really great so far. And I certainly don't mind coding conventions, they make for better code. I'm not complaining that the coding convention exists, I'm just trying to understand it so that it's easier for me to follow it.

Sod the comment, that superfluous indent before the brace at the start of the function would be enough to drive me up the wall! lol

My C# coding standard basically comes down to: "do whatever ReSharper does, because it's too much hassle to fight it, and at least it's consistent."

Ah, that was a cut and paste error when I pasted the code into the message.

Counterpoint: http://antirez.com/news/90

As one of the commenters on that thread has already sort-of said: if he thinks a title and a one-line synopsis are two different things, then I feel sorry for readers of his newspaper. ("I changed SystemThread::activate to return a boolean. You won't believe what happened next.")

Peter

Agh! Clickbait headline without a link! My worst nightmare! How will I ever know what happened next????

I took the liberty of adding a link. I hope Peter doesn't mind...

AGH!!!! Again????? How many times am I going to fall for this???