Live data from Hacker News

What was the strangest coding standard rule that you were forced to follow?

stackoverflow.com

81–83 of 83 posts

Re: What was the strangest coding standard rule that you were forced to follow?

#81
post #56

Earlier quoted context omitted.

I too was forced to do that. I too found it ridiculous. But not for long. There was a utility for generating the documentation strings (it got them right most of the time) and there's a lot to be said for consistency, even if it produces the occasional pointless-looking artefact. The reason this requirement is in the C# style guidelines is because it gives a consistent way of commenting and, of course, allows extract…

There wasn't "the occasional pointless-looking artifact"; I would have been fine with that. 95% of all code comments merely mimicked the type signature. People were using Visual Studio plugins to autogenerate the "documentation". Pressing SHIFT+ALT+J (or something) would read the function name and type signature and regurgutate some XML doc matching it. > allows extraction of documentation and intellisense. These alr…

If you're using a tool like Sandcastle to generate separate documentation, it won't produce decent output for elements that don't have XML comments. For that reason, while I also find those comments to be irritating I'm still in favor of a requirement that they be present for anything that's meant to be consumed by third parties.

Also, it sounds like some of the problem you're describing could have as much to do with people being slackers about the rule, than the rule itself. Someone should be taking charge of making sure these XML comments are useful, high-quality comments. There's almost always more information that should be provided beyond re-iterating the element's name. For example, the XML comments for a property named "IsValid" should reference some documentation of exactly what defines a valid state for that class. Numeric properties should very likely have notes about what unit denominates them. At the absolute least, make sure that every property's descriptive comment starts with "Gets", "Sets", or "Gets or sets".

Just to get in ahead of an obvious answer, let me also go ahead and say that if this is a situation where it's reasonable to tell users that they should just RTFS, then obviously this is a situation where there's not necessarily any need to require XML comments in the first place. But if you do need to require XML comments, you should also be requiring proper XML comments.

Re: What was the strangest coding standard rule that you were forced to follow?

#82

Earlier quoted context omitted.

What I've always found an intriguing idea is to store the abstract semantic graph of the program instead of (just) the text of the program in the revision control system. The source code could then be formatted / visualized in any way for the programmer while manipulating it. Kind of like a TeX, or CSS, but for source code. And I suppose it could also help with making sensible diffs, no longer need to be annoyed by a…

"A language should be designed in terms of an abstract syntax and it should have, perhaps, several forms of concrete syntax: One which is easy to write and maybe quite abbreviated; another which is good to look at and maybe quite fancy, but after all, the computer is going to produce it; and another, which is easy to make computers manipulate." --John McCarthy, http://www.infoq.com/interviews/Steele-Interviews-John-M…

Coffee Script / JavaScript dualty?
Post reply on HN