- Feature Articles
- CodeSOD
- Error'd
-
Forums
-
Other Articles
- Random Article
- Alex's Soapbox
- Announcements
- Best of…
- Best of Email
- Best of the Sidebar
- Bring Your Own Code
- Coded Smorgasbord
- Mandatory Fun Day
- Off Topic
- Representative Line
- News Roundup
- Editor's Soapbox
- Software on the Rocks
- Souvenir Potpourri
- Sponsor Post
- Tales from the Interview
- The Daily WTF: Live
- Virtudyne
Admin
underscore em instead of em underscore is already an epic frist step.
It might just be a note that the variable means the opposite of what its name says, which is high-grade WTF in its own right.
Admin
Combine this with ternary and your life is complete.
Admin
I thought it wasn't "clearer", but "more clear"
https://what.thedailywtf.com/topic/27385/word-count-inflation-olympics
Admin
Hungarians do not falsely support the trueness of this line.
Admin
Only bit missing is the explanation that Boolean.FileNotFound indicates the presence of a file. I admit though when you have policies that enforce xmldoc comments for all public properties or parameters to public functions (because they're used to auto generate sdk or api documentation) it's hard to avoid the occasional seemingly useless comment explaining that for instance "UseQuotes" should be true to use quotes. Especially if you also have a policy encouraging use of self-documenting code!
Admin
A number of the newer C# web services projects that I'm working on have exceedingly aggressive StyleCop settings regarding documentation and other rules. Comments are mandatory for every class, method, and property and result in comments like "Constructs an instance of the FOO class", "Gets or sets the BAR property", "This is the BAZ parameter". These fulfill the letter of the law but in no way improve readability and, in the case of property comments, require up to 4x the screen vertical real-estate, making the entire class all that harder to grok in one eye-full.
Admin
This sounds like a WTF in training....
Admin
Every time I see someone try to solve a documentation problem with something like StyleCop, it always creates useless documentation. The only way to fix documentation problems are by training and code review.
Documentation is a people problem. It needs to be solved by people.
Admin
Exactly. A good rule (which I try to follow in my code as I'm thankfully not bound by any stupid "guides"), is to write self-documenting code whenever possible and comments only where the code is not self-documenting or contains non-obvious subtleties. So by corollary, there will be as few comments as possible.
This goes for API documentation too, if not especially so. I hate reading APIs with dummy comment haystacks in which I have to find the actual declaration needles.
Admin
[quote]No one wants to see a method called addOneToSet and a comment that tells us Adds one item to the set.[quote]
Well, at least it gets clear that not "1" as an integer is added to the set. ;-)
Admin
Both work. It's like how the past tense of "dive" is both "dived" and "dove."
Admin
...and no fewer. ;)
Admin
Shocked to find nobody posted something like
Admin
I was once working on a project for a client for which they needed to directly interface with a java package that we'd provided as an add-on to our flagship product. And of course, as they are so entitled to do, they wanted the java API. We (as a company) hemmed and hawed and delayed the inevitable, but in the end I was the one who was on point, so to speak, and so I was the one to present it to them.
All the public methods which were provided for them to integrate their code into had javadoc messages like "I suppose we're going to have to document what this method does at some stage" and "bu66ered if I can remember what this does, I wrote it weeks ago" and similarly helpful stuff like that.
Never been so happy to jump on a plane to go home in my life.
Admin
Charles Simonyi lives!
Admin
Whilst I agree that for the most part autogenerated coments are cancer I do think that at least for a public API a policy of forcing comments on each method would be a good thing.
The problem with API documentation is that what is obvious and self documenting for the API creator might not be for the end user. Simple fact is that by the time you are done with writing and testing a method you are so used to it that it's easy to overlook subtleties that the end user really, really does want to know. An example would be the StopAllCoroutines function in unity. Nowhere in the public documentation does it say that it actually only stops those started in one of the two available ways for doing so. WTF indeed.
So I would argue that forcing a policy of commenting all API methods would be a good thing as it would force the developer to stop and think about his methods and if they need something mentioned. Which in turn would, absent autogenerated cancercomments result in more of those cases actually being covered.
Indeed, for a public API I would argue that an integral part of the code review process should be looking at each method and asking: Is there something here that should perhaps be noted in the comments.
Admin
Something like StyleCop enforces that function/attribute comments exist, code review is meant to enforce that those comments are useful.
Admin
Sure but not if that is an autogenerated header like
/** Stops all coroutines. */
If a function on an API is non obvious then code review should insist on the docs being added (and meaningful). Enforcing docs on every public function just means people get into the habit of autogenerating it, and then it doesn't get caught when it needs to be better than that.
I've managed to get that rule taken out of our static analysis here :) so now we only have to put Jdoc on when it adds value. Which is subjective, sure, but that's why you have reviews and multiple people looking at things.
Admin
Erm... yes. Yes, he does. 71 years old as I write this. I don't think he'd approve of this form of WTFsHungarian.
Admin
So... what happens when code review concludes that commenting nine out of ten properties is a waste of a highly paid resource's time? By this point, it's too late to get that time back.
The point is that the rule "every X must have a comment" isn't really what we want. We want the rule to be "things should be commented where necessary", and that rule cannot be applied by StyleCop. Therefore, it's a code review task.
Admin
I agree with your last sentence -- but I'll add that the answer may well be "no", and indeed should be in most cases. Put another way, if a large fraction of the API needs such comments about non-obvious behaviour, maybe the design just sucks.
Admin
True to use quote value. True if false, false if not. Dem stew with salt, dem stew without.
Admin
Today documentation tend to be written by "Technical" writers knowing too little about the needs of a programmer and more towards marketing. "Documentation" on the internet contains a lot of words but no content.