- Feature Articles
- CodeSOD
- Error'd
-
Forums
-
Other Articles
- Random Article
- Other Series
- 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
/*
Admin
Admin
Admin
Admin
Comment on this!
Admin
Admin
With a "tool" like this, you're practically insisting that comments are specifically generated "to satisfy Checkstyle." Way to go, sucking all the life out of the development process.
Mind you, it's in Java, so I don't suppose anybody would notice.
Admin
Man. I wish this was as bad as it got where I work. If "central IT" has people who know what a CVS hook is or that they care that anything is documented, they are better than most of the people I work with.
Admin
A positive point of mandatory comments for public members is that it pushes towards avoiding making any random routine public. If writing a comment is a bigger hassle than cleaning up the class to avoid unnecessary exposing of its guts, then that even may become a good thing.
At least it works for me that way.
Admin
I have plenty of unit tests like this:
/**
Admin
Personally, I try to make code self-documenting. If you're making the code so clever that it can't be understood without a comment, then something needs to be redesigned. In C and C++, because you have access to so many low level details, there is a temptation to resort to cleverness to get the job done.
I once thought about designing a language where there is no provision for explicit comments. Exceptions would be allowed to accommodate wonky third party APIs (e.g. declare [function] [library] [comment]), and debug tracing code (e.g. debug([comment])). Authorship, copyright and related would be an explicit component of a class, function, etc.
Admin
Whereas it might be complicated to discover which members are not documented at all, depending on your IDE, or lack of one, it's a relatively simple search to find all instances of DOCUMENT ME, and correct them.
Admin
(a) DRINK ME or (b) EAT ME?
I know which one 99% of the programmers on your project would recommend.
Admin
Sticking "DOCUMENT ME!" all over the place doesn't help. Treating that as a solution... <sigh>
Mind you, I once had to deal with a codebase where every getFoobar() method was "documented" with the obvious "get foobar", with no mention of what a foobar was, why you might want one, or whether you were getting a singleton, a new instance, or something from a pool. You know, anything that might have actually been useful.
Admin
i++; // Increment i by one
I recently encountered a web app from the ASP.Net 1.1 days, when all the server controls were declared in the codebehind (before VS started hiding them in partial classes). Someone had gone through a list of about 30 controls and commented above each one exactly what the control was. So it looked like this, repeated 30 times:
// System.Web.UI.WebControls.Textbox Protected System.Web.UI.WebControls.Textbox txtFirstName;
Admin
Bingo. Javadoc will generate very useful information without you putting in what are most often redundant comments (or lies, as neveralull suggests). You just have to learn how to create method and argument names that are meaningful (which also means that you have to understand SRP so that you can compose methods that can be concisely described). (Sadly, it doesn't happen often, as too many of us don't have a clue about cohesion.)
Admin
There are chuckleheads who insist that even non-public methods have javadoc comments...
Admin
Aw, I was expecting the code to parse the source and replace those tags with actual documentation.
Admin
Everyone knows that maintenance programmers who have to deal with non-public methods are psychic, and know that the method was supposed to do long before you've even written it. What would they need comments for?
Next thing you know, some chucklehead will claim that decent documentation tools can produce different output depending on whether you ask for public documentation or all documentation, and that's insane.
Admin
I can clearly remember how offended I was by the original Sony Playstation documentation where there was minimal documentation of the functionality and most of the functions had this line:
Return: This function returns a value
Needless to say there was nothing self documenting about the code and there was much whining from all of the developer groups with which I was working.
When I got the chance to write the audio os for the sega Dreamcast I jumped at it despite Segas terrible reputation just so that I could spare my friends that kind of lame ass shite.
I have no opinion whatsoever. none.
Captcha: immitto
Admin
Admin
Admin
1.
Admin
Actually, I think this is a pretty good idea. These sort of comments will show up as a reminder to document and pick out who it was that didn't document their code for a bit of a scolding to finish off the job.
Admin
Come to my party Come sing along Come watch me kick myself in the balls!
And then I'm gonna kick my dog in the balls!
Admin
Admin
Admin
Admin
Admin
Admin
Error: SUPREME BEING is null or not an object
Admin
/*
*/
Admin
53.8% javadoc, that's a lot!
Admin
Admin
The real WTF is that they didn't stick a TODO in there. At least without a Javadoc, an IDE could tell you one was missing. Now they're worse off than no documentation.
Admin
As a vendor, I've inherited products that had no decent documentation, and had to call friendly customers to ask whether certain behavior was correct or not -- it wasn't that I couldn't understand what it was doing, it was that without doc, I couldn't tell if that was what I wanted it to do.
I see this "Read the code, don't need comments" position again and again, and I'm sorry, but it's flat-out naive and shows a lack of experience in the real world. And it scares the hell out of me, having lived the nightmare too many times.
Admin
Well-documented code, in my experience, is at least 50% comments.
Admin
Next thing you know, some chucklehead programmer who insists on wasting time with formatted comments for private methods might actually take the time to fire up a web page and navigate to the appropriate spot in the pretty web pages to read such a comment.
Admin
This puts you in the class of people who don't understand cohesion.
Admin
Admin
Used to feel the same way, until I worked at a place where I was required to include contact information in the source. I realized then that:
If where I'm working requires comments, I just run a utility to stick a block at each function, and permute the declaration - e.g. STATUS BusterBrown::LikesWarmMilk(const char *you_bet) -> LikesWarmMilk for BusterBrown, takes const char pointer and returns STATUS.
Admin
Admin
Anyone care to share an example of checkstyle (or whatever was used) being called in the exact manner that this document refers to ?
I REALLY need to set up something like this in my company ASAP
Cheers, Ro
Admin
This sounds like a job for localization of your code. Run the program source through a message catalog before compiling...
Admin
Admin
Admin
I see both sides on this one.
On the pro side, the tool meets the absurd requirement. The tool points out what you need to document and lays it out in the right format.
On the con side, the tool bypasses the point of the requirement. The tool also crowds the code with useless nonsense.
The real WTF is, of course, the requirement that the code appear to have comments per some automated test rather than a requirement that it actually be appropriately commented.
The over-arching, all-inclusive WTF is the idea that code can be usefully measured using metrics calculated by automated code-scanning tools.
Admin
Admin
Admin
The book is already written: "JPod" by Douglas Coupland.
http://en.wikipedia.org/wiki/JPod
--