The Daily WTF: Curious Perversions in Information Technology

2013-01-17 Reply Admin

Comment On Comment On Comments

PedanticCurmudgeon · 2013-01-17 Reply Admin

catch(Exception ex)
{
  // Please don't post this to thedailywtf.
}

There, fixed.

2013-01-17 Reply Admin

Comments certainly don't tell what the code does. The code is there for this. Comments can tell why the code does something.

At least, that's how I see comments ...

dkf · 2013-01-17 Reply Admin

I can well believe Dante's comment as being part of some crufty old template handling system, probably lovingly thrown at the wall in Perl.

The MAZZTer · 2013-01-17 Reply Admin

Last one probably isn't a WTF.

Likely their server-side process replaces the text "" with some real HTML before sending it client side. Crude, but it works. Some idiot probably thought it was just a useless comment and deleted it without asking anyone, hence the comment before it.

2013-01-17 Reply Admin

The MAZZTer:
Last one probably isn't a WTF.
Likely their server-side process replaces the text "" with some real HTML before sending it client side. Crude, but it works. Some idiot probably thought it was just a useless comment and deleted it without asking anyone, hence the comment before it.

except that is doesn't say why INFERNO is needed... and when it would no longer be untouchable.

2013-01-17 Reply Admin

Pino:
Comment On Comment On Comments

Comment On Comment On Comments.

2013-01-17 Reply Admin

Please be careful when spelling carefull.

Auction_God · 2013-01-17 Reply Admin

Comments show where the bugs in the code are: The developer thought that it was difficult enough to require an explanation and therefore this is where they most likely made a mistake!

2013-01-17 Reply Admin

Aris:
Comments certainly don't tell what the code does. The code is there for this. Comments can tell why the code does something.
At least, that's how I see comments ...

I couldn't agree more.

Except there are some 'Agile' people who out there who 'don't gold plate' and will tell you documentation is just another thing to maintain. Saying 'why' usually changes less often than 'how' but apparently we are all to stupid to understand their genius (or their Worse Than Failure code).

2013-01-17 Reply Admin

Auction_God:
Comments show where the bugs in the code are: The developer thought that it was difficult enough to require an explanation and therefore this is where they most likely made a mistake!

WRONG. Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand. They should be language and implementation neutral, and concise enough to be written carefully. If your code has comments saying 'add one because we've got an offset I can't figure out' then you've got a crap team. If all your team don't comment then please let us know your company so I never apply for a job there.

no laughing matter · 2013-01-17 Reply Admin

Wronged:
Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand.

Probability that "the business" reads the code: <0.0001

Probability that another developer reads (and tries to understand) the code: 1

2013-01-17 Reply Admin

From an actual project I did at University:

[code]class Flash /* AaaAAAAAAAHHHH */ : public PhysicsBehaviour // Saviour - of the UniVERSE! { ... }

ObiWayneKenobi · 2013-01-17 Reply Admin

The thing that really annoys me is comments that indicate the person writing the comment either had no idea what the code was doing, or worse was too lazy to refactor it to make sense.

My old job was littered with comments like:

// not sure where this is used

// why is this here?

// not sure what this code does

// there is probably a better way to do this

and it annoyed me because it was always the same guy, and this guy would never take 5 minutes to address it; he would copy/paste code 3+ places rather than spend the time to refactor it to a method, or just comment out a large block of code and never remove it (despite the fact we used version control) because he was worried that COMMENTED OUT CODE might break the system (no joke he said as much once).

Bad comments are worse than no comments at all, and best of all is code that is actually readable without needing a comment to explain it. Sure, maybe have a comment if the code is for a particular workflow process, but in most cases I firmly believe code should document itself by being clear and concise.

2013-01-17 Reply Admin

Beginners comment nothing. Apprentices comment the obvious. Journeymen comment the reason for doing it. Masters comment the reason for not doing it another way. -- Richard C. Haven

2013-01-17 Reply Admin

// begin comment activity 399412

Don't you just hate it when you see this retarded shit everywhere? This is the wrong tool for the job. This is what source control history is for.

// end comment activity 399412

I've actually seen this, except "Bob" left the company years ago, so I had no one to yell at/ask about it:

// Bob added this for paging new AbstractFactory().getManagerObject().doPaging();

WhiskeyJack · 2013-01-17 Reply Admin

Andrew:
// begin comment activity 399412
Don't you just hate it when you see this retarded shit everywhere? This is the wrong tool for the job. This is what source control history is for.

// end comment activity 399412

Sometimes I'll see, and add myself, comments like:

// Added by W.Jack, 11/11/11, Problem Report 12345 // If the mode is X, then ensure Y is set

It's also described in the version control history, as well as the problem report description, and all that good stuff, but if you're in the middle of reading/examining/editing the code, a quick 2-line note like that to remind you of some special circumstance that was taken care of, is quicker than stopping to do a diff and then firing up the reporting tools to figure out why.

Obviously we don't go overboard, and we wouldn't bother to comment silly stuff like:

// Oops, forgot to check for null pointer here

// Fixed spelling mistake

// Removed this entire function as it is no longer needed

But the major logic bugs, "don't forget to do X before Y", etc. are helpful.

2013-01-17 Reply Admin

I'm an agile guy :) I don't write a lot of comments, but I make sure the one I write are useful and I make sure I write comments where it's needed.

And if I was in the situation where an important markup had not to be deleted, I'd certainly comment not to delete it. In agile, you are not afraid to change code that's working to make it better. And there's no code ownership.

2013-01-17 Reply Admin

Aris:
Comments certainly don't tell what the code does. The code is there for this. Comments can tell why the code does something.
At least, that's how I see comments ...

QFT. The code already documents WHAT. If you can't understand the code then you're not a programmer and should GTFO. It's the WHY that you need explained.

2013-01-17 Reply Admin

The MAZZTer:
Some idiot probably thought it was just a useless comment and deleted it without asking anyone, hence the comment before it.

The idiots are the ones that don't think to change it. If you have ridiculous code in your code base that shouldn't be required or could be done much better and you don't want to change it then I'd say you're the idiot. Now, if it's got a comment guarding it to say don't change it then that's another story, but if it doesn't explain WHY not to change it then track down the commits that added it in version control and ask the author about it (do you use version control, right?).

Steve The Cynic · 2013-01-17 Reply Admin

ObiWayneKenobi:
The thing that really annoys me is comments that indicate the person writing the comment either had no idea what the code was doing, or worse was too lazy to refactor it to make sense.
My old job was littered with comments like:

// not sure where this is used

// why is this here?

// not sure what this code does

// there is probably a better way to do this

Or one I saw once, probably worse than all the above:

/*
 * Don't know why this doesn't work.
 */

WTF? I looked at the identified problem, and traced through the code, withoutrunningit. I spent ten minutes correctly identifying why it didn't work, and about an hour unsuccessfully removing all traces of withering contempt from my emailed discussion of the problem.

2013-01-17 Reply Admin

Wronged:
WRONG. Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand. They should be language and implementation neutral, and concise enough to be written carefully. If your code has comments saying 'add one because we've got an offset I can't figure out' then you've got a crap team. If all your team don't comment then please let us know your company so I never apply for a job there.

You should only comment code that isn't clear (and most of your code should be clear without them). You should definitely not be using business terminology in the code unless it's vital to understanding the code. The code should be logical, but the business world usually isn't. The comments are for developers, not management.

2013-01-17 Reply Admin

Wronged:
Auction_God:
Comments show where the bugs in the code are: The developer thought that it was difficult enough to require an explanation and therefore this is where they most likely made a mistake!

WRONG. Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand. They should be language and implementation neutral, and concise enough to be written carefully. If your code has comments saying 'add one because we've got an offset I can't figure out' then you've got a crap team. If all your team don't comment then please let us know your company so I never apply for a job there.

I think you are waay to subtle for anyone to bite on this troll attempt.

ObiWayneKenobi · 2013-01-17 Reply Admin

Andrew:
// begin comment activity 399412
Don't you just hate it when you see this retarded shit everywhere? This is the wrong tool for the job. This is what source control history is for.

// end comment activity 399412

I've actually seen this, except "Bob" left the company years ago, so I had no one to yell at/ask about it:

// Bob added this for paging new AbstractFactory().getManagerObject().doPaging();

I do kind of hate those kind of

// jsmith Ticket 343243

kind of comments since that's what version control is for, but I do kind of see where it might be useful if you crack open a code file to see where a fix was done.

I hate hate hate HATE having huge "change log" blocks at the top of a code file though.

2013-01-17 Reply Admin

Anonymous:
Wronged:
WRONG. Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand. They should be language and implementation neutral, and concise enough to be written carefully. If your code has comments saying 'add one because we've got an offset I can't figure out' then you've got a crap team. If all your team don't comment then please let us know your company so I never apply for a job there.
You should only comment code that isn't clear (and most of your code should be clear without them). You should definitely not be using business terminology in the code unless it's vital to understanding the code. The code should be logical, but the business world usually isn't. The comments are for developers, not management.

Swedish tard:
I think you are waay to subtle for anyone to bite on this troll attempt.

... I stand corrected.

2013-01-17 Reply Admin

no laughing matter:
Wronged:
Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand.
Probability that "the business" reads the code: <0.0001
Probability that another developer reads (and tries to understand) the code: 1

Probability business will ask you to describe the process they have paid for: 0.7 Probability human being will read code: 1.0 Probability they will be a good software engineer: 0.3 Probability they will be experienced: 0.5 Probability business get good value in response to their question: ? Impossible to tell, depends which Dastardly & Muttley T-shirt wearer is asked.

If the comment already says what is happening, probability you can paste this into an email: 0.8

2013-01-17 Reply Admin

ObiWayneKenobi:
The thing that really annoys me is comments that indicate the person writing the comment either had no idea what the code was doing, or worse was too lazy to refactor it to make sense.
My old job was littered with comments like:

// not sure where this is used

// why is this here?

// not sure what this code does

// there is probably a better way to do this

Those comments seem normal to me. There's nothing wrong with making note of WTF code that doesn't make sense. If you don't understand it then you can't safely refactor it. It's about making note that something is fishy and you or somebody else should review it when you get a chance. It could also just be a reminder to ask somebody about it when you get a chance. I like to use #warnings for that though.

ObiWayneKenobi:
and it annoyed me because it was always the same guy, and this guy would never take 5 minutes to address it; he would copy/paste code 3+ places rather than spend the time to refactor it to a method, or just comment out a large block of code and never remove it (despite the fact we used version control) because he was worried that COMMENTED OUT CODE might break the system (no joke he said as much once).

I've worked with this type of person before. Yes, they will drive you insane. The comments aren't the program. The copy/pasta, superstition, and incompetence are the problem. :P Anybody can be a code monkey, but it takes something special to be a competent programmer.

2013-01-17 Reply Admin

Comments: Why Tests: What Code: How

2013-01-17 Reply Admin

Really, Remy? That's the only comment you put in this one?

I can't tell if you're taking a minimalist tack with your humor, or if you're just losing your touch... ;-)

2013-01-17 Reply Admin

Wronged:
Auction_God:
Comments show where the bugs in the code are: The developer thought that it was difficult enough to require an explanation and therefore this is where they most likely made a mistake!

WRONG. Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand. They should be language and implementation neutral, and concise enough to be written carefully. If your code has comments saying 'add one because we've got an offset I can't figure out' then you've got a crap team. If all your team don't comment then please let us know your company so I never apply for a job there.

I disagree.

The language for why should be the language that the next programmer can understand.

Product documentation is where you write the whys that the business guys can understand. Business guys have no "business" reading your source code, unless they are fully apt developers themselves. Even then, if the VP is reading code, he doesn't trust his teams' leaders and there's a management issue.

Not only that, but comments CAN describe what a section of code is designed to do, if the code is complex and requires that information to maintain it. Example, code that performs a complex algorithm, I usually comment what the algorithm is supposed to do and how it should accomplish that. In these cases, any sufficient self-documenting function names or class names would end up a WTF article for their names.

In short, use common sense when writing comments, and target your audience. That's what you're taught when writing product documentation, so the same rules apply for comments, for the same reasons.

2013-01-17 Reply Admin

Anonymous:
Wronged:
WRONG. Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand. They should be language and implementation neutral, and concise enough to be written carefully. If your code has comments saying 'add one because we've got an offset I can't figure out' then you've got a crap team. If all your team don't comment then please let us know your company so I never apply for a job there.
You should only comment code that isn't clear (and most of your code should be clear without them). You should definitely not be using business terminology in the code unless it's vital to understanding the code. The code should be logical, but the business world usually isn't. The comments are for developers, not management.

And that my friends is why software is often so poorly designed, badly written, buggy and late - because IT people think domain knowledge is 'management speak' and refuse to use it.

no laughing matter · 2013-01-17 Reply Admin

anon:
Probability business will ask you to describe the process they have paid for: 0.7

So that's how it is working in your company: Business manager: "Here are 20.000$, write us some code!" anon-prog: Codes along 10KLoC Business manager: "How many lines-of-code so far?" anon-prog: "ten thousand" Business manager: "Not enough, write another ten thousand!" anon-prog: Codes along another 10KLoC Business manager: "How many lines-of-code now?" anon-prog: "twenty thousand" Business manager: "Very good. Now explain to me what the code does!"

anon:
If the comment already says what is happening, probability you can paste this into an email: 0.8

Probability that the comment is outdated or plain lying: 0.5

2013-01-17 Reply Admin

Gomer Pyle:
The MAZZTer:
Last one probably isn't a WTF.
Likely their server-side process replaces the text "" with some real HTML before sending it client side. Crude, but it works. Some idiot probably thought it was just a useless comment and deleted it without asking anyone, hence the comment before it.

except that is doesn't say why INFERNO is needed... and when it would no longer be untouchable.

Well, the time when the INFERNO thing is no longer untouchable is the time when they rewrite the code, which while that is not going to happen any time soon still has a much greater chance than that anyone is going to update the comment with a better explanation.

2013-01-17 Reply Admin

WhiskeyJack:
Andrew:
// begin comment activity 399412
Don't you just hate it when you see this retarded shit everywhere? This is the wrong tool for the job. This is what source control history is for.

// end comment activity 399412

Sometimes I'll see, and add myself, comments like:

// Added by W.Jack, 11/11/11, Problem Report 12345 // If the mode is X, then ensure Y is set

It's also described in the version control history, as well as the problem report description, and all that good stuff, but if you're in the middle of reading/examining/editing the code, a quick 2-line note like that to remind you of some special circumstance that was taken care of, is quicker than stopping to do a diff and then firing up the reporting tools to figure out why.

Obviously we don't go overboard, and we wouldn't bother to comment silly stuff like:

// Oops, forgot to check for null pointer here

// Fixed spelling mistake

// Removed this entire function as it is no longer needed

But the major logic bugs, "don't forget to do X before Y", etc. are helpful.

I give you a 50% - The note about the reason for the fix is good. The note about who added it, when, and for which problem report is irrelevant to the code itself.
Instead just put the reason for the fix and leave the rest of the information in the commit message. If you come to such a line and want to know who added it when for what bug ticket (or other circumstantial information about the change itself) the source history (svn and I'm sure other more sophistocated version control tools have a nice feature called Blame or Annotate which will show you who last changed each line when and what the commit message was) is not so hard to access, especially when using a modern IDE with proper VCS integration.

2013-01-17 Reply Admin

no laughing matter:
anon:
Probability business will ask you to describe the process they have paid for: 0.7
So that's how it is working in your company: Business manager: "Here are 20.000$, write us some code!" anon-prog: Codes along 10KLoC Business manager: "How many lines-of-code so far?" anon-prog: "ten thousand" Business manager: "Not enough, write another ten thousand!" anon-prog: Codes along another 10KLoC Business manager: "How many lines-of-code now?" anon-prog: "twenty thousand" Business manager: "Very good. Now explain to me what the code does!"

Far further from the truth than you can possibly imagine.

Remy Porter · 2013-01-17 Reply Admin

For all that comments should document "why it does" and not "what it does", there are enough business processes that are non-obvious and poorly understood that it's often easier to explain what the code is doing, too.

For a recent project, I had to write a bunch of math. I understood the math when I wrote the code, but I do not understand it any longer. I do not know what the code does, other than "this derives this set of calculations from the input waveform". Without comments to walk me through the math, I wouldn't be able to maintain the code.

2013-01-17 Reply Admin

I see absolutely nothing wrong with the existence of comments like "this is a hack", "I don't like the way this is done, but I couldn't think of a better one", or even "this isn't working right now, beware!" Yes, in a perfect world, everything would always be perfect, but that isn't the world we live in. Sometimes we need to commit things that only mostly work, or that totally work but aren't pretty, and immediately above such a code section is the perfect place to document that fact (at least assuming you aren't working with a noncompiled language where the source will be pushed directly to curious consumers :p).

What I really love are people who feel the compulsion to comment every public method... but don't feel the same need to have those comments actually be useful, or even mean anything. I worked with one guy like that, who thought it would be a good idea to run a comment auto-generator. I guess he thought it would encourage us to replace the autogenerated comments with real ones when we saw them? Actually it just encouraged us to be amused, and then ignore them. Properties with names like FirstName, for instance, don't really need comments. And what they definitely don't need is comments like:

        /// 
        /// Gets or sets the first name.
        /// 
        /// <value>The first name.</value>
        public string FirstName

But at least that's still readable. What they really don't need are comments like (real examples!):

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

Or:

/// Internals the extract icon.
private static Icon InternalExtractIcon(string file)

Or:

        /// 
        /// Removings the profile event handler.
	/// 
        public delegate void RemovingProfileEventHandler(object sender, RemovingProfileEventArgs e);

Or:

	/// 
	/// Toes the type of the workflow.
	/// 
	public static string ToWorkflowType(int pdfFieldType)

Or even:

        /// 
        /// Determines whether the specified item is item.
        /// 
        /// <param name="sessionItem">The session item.</param>
        /// <returns>
        ///     <c>True</c> if the specified item is item; otherwise, <c>false</c>.
        /// </returns>
        public bool IsItem(SessionItem sessionItem)

2013-01-17 Reply Admin

Remy Porter:
For all that comments should document "why it does" and not "what it does", there are enough business processes that are non-obvious and poorly understood that it's often easier to explain what the code is doing, too.
For a recent project, I had to write a bunch of math. I understood the math when I wrote the code, but I do not understand it any longer. I do not know what the code does, other than "this derives this set of calculations from the input waveform". Without comments to walk me through the math, I wouldn't be able to maintain the code.

Makes sense.

All one must do is stand back and realise that no guideline on commenting is gospel just like no development methodology is perfect.

Every approach has its place in any reasonably interesting project, and as long as the people writing the code continually strive to improve their craftsmanship then the chances of a successful outcome and straightforward legacy maintenance are good.

Steve The Cynic · 2013-01-17 Reply Admin

Remy Porter:
For all that comments should document "why it does" and not "what it does", there are enough business processes that are non-obvious and poorly understood that it's often easier to explain what the code is doing, too.
For a recent project, I had to write a bunch of math. I understood the math when I wrote the code, but I do not understand it any longer. I do not know what the code does, other than "this derives this set of calculations from the input waveform". Without comments to walk me through the math, I wouldn't be able to maintain the code.

Ah, wisdom... The essential point is that the comments should provide useful information for the maintainer.

If you are writing a "what it does" comment, you will usually find it more useful to use problem-domain language rather than solution-domain language. This isn't so that the business-side people can understand the code - that theory of code creation was thoroughly, if unintentionally, debunked by the inventors of COBOL back in the Fifties.

No, it is because that way the comment can add something above and beyond the content of the code. "Add fleen to ogglefloggle and store the result in argleflargle" doesn't add anything to this line of code:

  argleflargle = fleen + ogglefloggle;

In fact, well-chosen variable names, which 'fleen', 'ogglefloggle', and 'argleflargle' are unlikely to be, will most often remove any need for a comment here. A more complex series of operations would probably benefit from a description of what, but equally you could just write a reference to a book or other piece of descriptive reference material. "Perform the routing summary calculations as described in [Miffle and Swub 1998]" might be a suitable example.

2013-01-17 Reply Admin

no laughing matter:
Wronged:
Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand.
Probability that "the business" reads the code: <0.0001
Probability that another developer reads (and tries to understand) the code: 1

What are the chances that a developer, that can understand the IT-speak that is the code, was given tasking in business terms? Just because I can figure out what a block of code does doesn't mean I don't need to understand the business logic that makes that code necessary. This is the same reason why you use variable names that are descriptive of the business logic: a=bc has no inherent meaning, but amountBilled=multiplierDiscountamountTaxed does. Which code would you rather see when tasked to ensure the discount does not exceed 15%?

chubertdev · 2013-01-17 Reply Admin

I inherited a web app with a ton of these comments:

Try
   ...
Catch ex As Exception
   ' this should never happen
End Try

I didn't replace the comment, but when I added exception reporting after it, let's just say that we were able to solve most of the bugs in the app.

2013-01-17 Reply Admin

Am I the only one disappointed that clicking "INFERNO" in a Remy article does not generate disco inferno popups?

Roby McAndrew · 2013-01-17 Reply Admin

Steve The Cynic:
Or one I saw once, probably worse than all the above:
/*
 * Don't know why this doesn't work.
 */

Long, long ago I had to add a comment like that (but the opposite sense). I forget the exact details, but I seem to recall it was a TurboPascal graphics library. For some reason calling a library function had no effect, unless you called it twice (same function, same parameters). So I ended up with something like:

(* I have no idea why this line has to appear twice, but apparently it does *)
SetTextColor(Red);
SetTextColor(Red);

It was a mark of how desperate I was that I even tried such stupid code, but it worked; so I commented it and moved on.

cellocgw · 2013-01-17 Reply Admin

chubertdev:
I inherited a web app with a ton of these comments:
Try
   ...
Catch ex As Exception
   ' this should never happen
End Try

Which shortly thereafter DID happen and the resulting notification window was submitted to the Friday Photo collection on TDWTF.

chubertdev · 2013-01-17 Reply Admin

I think the "don't know why this doesn't work" comments are pretty bad on their own, but definitely a WTF when compounded with the fact that they were bugs, and ones that were easily remedied.

As for a weird issue like calling something twice to get it to work, if you can't modify the referenced method, and the double references work, then it's not a WTF.

herby · 2013-01-17 Reply Admin

Pino:
Comment On Comment On Comments Oh, my!

FTFY

chubertdev · 2013-01-17 Reply Admin

cellocgw:
Which shortly thereafter DID happen and the resulting notification window was submitted to the Friday Photo collection on TDWTF.

It was mostly stupid stuff like this:

Try
   intRecordID = Integer.Parse(strRecordID)
Catch ex As Exception
   'this should never happen
End Try

It gets even better. The guy responsible for the code came back to the company, and I left shortly after that. I can only imagine how bad things are there now.

2013-01-17 Reply Admin

Jazz:
Really, Remy? That's the only comment you put in this one?
I can't tell if you're taking a minimalist tack with your humor, or if you're just losing your touch... ;-)

His attempt to go meta ...

But it's not a good comment: It tells us us just that he wouldn't put those things in an article directly, not but why (which is something I've really never understood).

2013-01-17 Reply Admin

Andrew:
// begin comment activity 399412
Don't you just hate it when you see this retarded shit everywhere? This is the wrong tool for the job. This is what source control history is for.

// end comment activity 399412

I've actually seen this, except "Bob" left the company years ago, so I had no one to yell at/ask about it:

// Bob added this for paging new AbstractFactory().getManagerObject().doPaging();

I occasionally write comments like this:

// changed by demand from Joe at SomeCustomer, fjf 2012-01-23

Especially for "special" behaviour that I expect will be revisited soon. So when some other (or probably the same) guy from SomeCustomer demands contradictory behaviour a few weeks later, we can ask them to sort it out internally first. And if a coworker gets assigned to it, they can contact me easily when necessary, without digging through revisions.

no laughing matter · 2013-01-17 Reply Admin

Sergeant Obvious:
no laughing matter:
Wronged:
Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand.
Probability that "the business" reads the code: <0.0001
Probability that another developer reads (and tries to understand) the code: 1

What are the chances that a developer, that can understand the IT-speak that is the code, was given tasking in business terms? Just because I can figure out what a block of code does doesn't mean I don't need to understand the business logic that makes that code necessary.

The place to describe the business requirements is the spec!

I know it is a tradition on this site that nobody has read the spec, but in the real world a developer not knowing the spec or describing the business logic in code comments instead of the spec (so that you can easily copy'n'paste it into a mail when anon's boss asks for the spec) is TRWTF.

Of course it is fine to add a reference to the spec in the code comments.

Comments

Leave a comment on “Comments”