The Daily WTF: Curious Perversions in Information Technology

2009-04-27 Reply Admin

Nothing like idiots to tell you that you are documenting things wrong. Then they provide a fix. And don't use the standard JavaDoc TODO tag in the fix.

2009-04-27 Reply Admin

dkf:
imu:
Wouldn't SUPREME BEING be a singleton?
Not at all! In India or ancient Greece or Egypt, it's not a singleton at all. And in other parts of the world, it's abstract, with no instances (other than Bruce Schneier, of course).

No, in some times and places people THINK that there can be multiple instances of supreme beings, while in others people think that there can be only one, and others think there is none at all. But clearly one group is right and the others are wrong. Just because there is confusion over the specifications doesn't mean that there is no right answer! Is this how you write your code? "The marketing department says that 'price' is an attribute of the Product entity, which would make the price the same for all sales at all stores, but the store managers say that it is an attribute of Sale because salesman can negotiate on-the-spot discounts. So I guess that means there is no right answer and we can throw it where ever we like!"

2009-04-28 Reply Admin

Bill:
Come on, I've seen much better machine generated documentation than that, mostly in Help dialog boxes:
calculateExpiryScale is a public int method that accepts 1 parameter: keyCode which is a String. It may throw a KeyCodeInvalidException if the KeyCodeInvalidException condition arises during processing.

And really, if you're any good, what more do you need to know?

If you're any good the function signature tells you that already. WIthout the pointless paragraphs...

2009-04-28 Reply Admin

/**

Kill flanders! */

neminem · 2011-10-28 Reply Admin

Late comment: I'd much rather autogenerated comments that just say "please put real comments here", than autogenerated comments that look like real comments until you actually read them, at which point you realize they're useless, and in some cases hilarious gibberish. Some real examples from our project, for the benefit of anyone else random wandering through old comments:

    /// <summary>
    /// Determines whether [is equal to] [the specified x].
    /// </summary>
    /// <param name="x">The x.</param>
    /// <param name="y">The y.</param>
    /// <returns>
    /// 	<c>true</c> if [is equal to] [the specified x]; otherwise, <c>false</c>.
    /// </returns>
    private bool IsEqualTo(List<CreateTokenInformation> x, List<CreateTokenInformation> y)

    /// <summary>
    /// Datas the grid view cell value changed.
    /// </summary>
    protected abstract void DataGridViewCellValueChangedCore(DataGridViewCellEventArgs e);

    /// <summary>
    /// Languages the comparer.
    /// </summary>
    /// <param name="first">The first.</param>
    /// <param name="second">The second.</param>
    /// <returns>
    /// Language comparer and returns a <seealso cref="Int32"/>.
    /// </returns>
    private int LanguageComparer(Display<object> first, Display<object> second)

    /// <summary>
    /// Pages the changed.
    /// </summary>
    private void PageChanged(object sender, EventArgs e)

Self-Documenting

Leave a comment on “Self-Documenting”