When writing code, some developers like to write notes to themselves/others in the actual code using “comments”. The intent is for documentation; to explain what the code is doing. It is often argued that code should be “self-describing” which is an idea I agree with. However, there can be complex functionality because it is technical, the developer struggled to come up with a simple version, or maybe the domain logic is just that way.
I’ve collated various examples, with various degrees of humour.
Confusing
Comments are supposed to add clarity to the code. When you see code that looks simple, but the comment seems to describe something else, is ambiguous, or misleading, then the comment has decreased clarity.
// Display save dialog
RefreshFilters();
...
// Save over existing filter
RefreshFilters();
You would think RefreshFilters would simply reload the filters. It sounds like it is prompting the user with a save dialog, and even overwrites the existing filter.
Self-deprecating
//Well I've messed this up!!!
//Ultimately a filter ends up adding something to the where clause,
// or if it's a relationships filter, then the AND clause of the join.
//The way I'm adding it to these is not clean and just sucks. (two constructors with lots
// of private variables that aren't needed half the time...yuk.
//Reading the above comment ages later, I'm not sure why relationships have to be on the
//join clause? If it's a left one then yes but you can have a left join to a logical table.
//TODO: I've messed up
/// Ok. I've messed up. I've messed up good and proper.
/// Aggregate reports wants to format a date as a year, say. The formatting stuff
/// is buried in compare functions (because ranges was the only place that I needed to do this)
/// There is the column.AddOutputFormatInformation that might be useful when this is fixed????
// This looks like a hack, and, frankly, it is. I'm sorry, I can't work out how to make this not stupid.
// If you're reading this and have some brilliant insight into how to make this work in a way that doesn't
// make people sad, please go nuts and fix it.
Criticising Others
(cg) => { return cg.DisplayName; })); // Wow this is awful
matchingSlotEntity.JobCategoryName = string.Empty; // This doesn't make sense. JobCategory belongs to a person, not a slot.
/// <summary>This is awful. Get Ryan to support Guids for Mail Merge</summary>
//Please. Remove word interop. Not even Microsoft want us to use it.
TaskCount TaskCount { get; set; } // TODO: Again, this should be readonly. Something mucks with it, though.
MessageBox.Show("Sorry this feature hasn't been implemented yet... :(", "Sad Info..!!");
Funny
// Reverse the order as they are stored arse about face
this.ribbonBars.Reverse();
// Show yourself!
/// <summary>
/// Builds trees for a living.
/// </summary>
internal static class MailMergeTreeBuilder
this.AllowDrop = false; // No dropping on this tree thankyou.
Even Microsoft throw in the occasional gem.
// At this point, there isn't much we can do. There's a
// small chance the following line will allow the rest of
// the program to run, but don't get your hopes up.
Useful Warnings
This one warns you that the logic is confusing.
/**********************************************************************************
Description
-----------
You'd think that a stored procedure called 'GetNextBusinessDay' would return the
next business day for an organisation. That would be too easy.
What this stored procedure does, is return a day that is not explicitly marked
as 'closed'.
It also doesn't return the 'next' business day in the default case where the parameter @BusinessDayOccurrence is set to zero - in that case it returns the current day, or the next non-closed day if the current day has a closure defined on it.
@BusinessDayOccurrence doesn't find the first non-closed day after X days from today, incidentally. It returns the Xth non-closed day, which is an important difference. If you have closed bank holidays, and want to know the 2nd non-closed day after 24th December, it's not 27th December but 28th December Confusing!
**********************************************************************************/
Stranger Coding Tings 