undefined | Better HN

0 pointsDeestan13y ago0 comments

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 already give you type signature and function name. If intellisense already gives you "bool isValid", what possible gains do you get from an extra "boolean value indicating whether the value is valid"?

> I am no drone by any means, but this isn't so insane if you give it some thought.

Trust me, I have given it plenty of thought. Some conclusions from these thoughts:

- Code comments that merely mimic the type signature add nothing. Not for readability, not for intellisense, not for documentation extraction.

- They increase the signal-to-noise ratio of the code immensely, making it harder to read. Comments with actual useful information will now drown in the sea of drivel.

- Fuck it, I'm not working here anymore.

The main fallacy here is that More Process and More Rules can make bad programmers write good code.

0 comments

afandian13y ago

Fair enough. I found that in a collaborative environment (people making and sharing code) the style guidelines had a net positive effect (and believe me, my first gut reaction was along the 'this is insane' lines). As process go, the degree of automation and strict automatic enforcement (and fixing) of rules felt lightweight after a bit.

We're neither of us going to convince the other, I just thought I'd add a datapoint. FWIW I now write Python and although PEP8 isn't as hard-line, I think it similarly does a lot of good.

bruceboughton13y ago

>> Code comments that merely mimic the type signature add nothing. Not for readability, not for intellisense, not for documentation extraction.

Agreed. In fact, over time, they are likely to be not merely useless but harmful as the API signature evolves over time, unless the developer also updates the (pointless) comment.

bunderbunder13y ago

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.

j / k navigate · click thread line to collapse