- 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
This comment represents the comments on this article
Admin
So standard Indian offshore contracting situation?
Admin
This comment represents the Comment attribute on the comment on this article.
Admin
And this is why we need certification, regulation and a bar. Also a disbarment ritual involving flame throwers and a sack of rabid weasels.
Admin
I feel the vendor is missing a trick here. As we all know, comments become unreliable as and when code changes.
For robustness, they should have made every comment the same:
"Ceci n'est pas une pipe."
Admin
"Voici une pipe: |"
Admin
Oh how lovely if that were the case. Here we'd be more likely to promote them to being the project manager of the next outsourced project.
Admin
Personally I'm for stoning with old office printers flung by trebuchet.
Admin
The worth of a comment is proportional to the (perceived) complexity of the code it comments on. The comments picked in the article seem worthless and even a joke, which could mean that the code is utterly self-explanatory. I'm undecided about this WTF due to a lack of code in the article.
Admin
If you combine Magritte and Pauli ("It's not even wrong!") then I contend that my comment is universal. Recall that Magritte labelled a painting of a pipe as "ceci n'est pas une pipe". Which means that the comment will always be correct, either literally or metaphorically.
I like your idea as a comment for a pure map-reduce system, though. The map would be Magritte and the reduce would be your version ...
Admin
So the TRWTF was bothering to ask for (even pay for) documentation from an outfit that writes code that badly? ... granted we had no examples.
Everything else seems pretty standard, except the bit Steve already commented on.
What's always surprised me is how hard it is to get the plug pulled on projects like this when they enter the death spiral (which is usually fairly soon after they start).
Admin
How is it that they had to pay more? How was their response to the request for more money not, "DGAF. Uphold the contract to which you agreed."?
Admin
I feel like we have not got the entire story. It seems odd to mean that management would basically uncritically side with the third party contractor when their internal people were telling them the SOW was not satisfied. Why would anyone responsible for cutting the checks just pay out a vendor for non-performance.
If you wanted to continue the relationship at all, you'd tell AP to short-pay them some reasonable amount for whatever they had delivered and type up a nice e-mail detailing your view the situation to someone in your legal department to take over primary responsibility for managing the relationship.
Part of me has a sneaking suspicion the contract was more along the lines of time and materials with certain priorities variety. The People at Josh's company did a poor job scoping the project and the vendor likely did an equally bad job when it came to clarifying requirements and expected deliverables and ensuring the bid matched the resources requirements for the scope. So the vendor wanting the work and not being overly concerned with the uncertainty if they could even do it, low balled the estimate. Josh's company wrote a contract that gave them litter protection. The business stake holders eventually got something that does a lot of what they want and are tired of throwing money at it. Josh and his team are crying about it being dumped in their laps.
Here is thing Josh thinks the vendor is as fault - he is wrong. His company is at fault and its his management he should angry with. He probably should have had a seat at the table at both vendor selection and scoping time.
Admin
I assume the contract was with an offshore company, so forcing them to follow the contract was probably pointless. Which is why I never wanted to deal with offshore companies no matter what the arrangement.
Admin
If the response is 'pay us to do it, or we'll go bust and not do it', what realistic choice do you have?
Admin
From my own personal experience, there's a degree to which management wants to fight with a vendor versus how much management thinks their own internal developers are griping to no purpose. Management doesn't understand the product, doesn't understand the purpose or application of code quality standards, etc. So they have the contractors telling them "it's fine," and the internal devs saying "no, it's not," and their instinct is to compromise because that's what management does.
Admin
These contracts are often not fixed price, they are time and materials against an estimate, with a percentage retained to be paid on completion. Have to be, or all these scope changes and elastic requirements would make it all impossible. Sounds like it was sloppily drawn up anyway, so they are obliged to provide the deliverables but what's included in the line items was vague. However it was divided up, documentation should have been included in each component/module.
Once we find out they hadn't been drawing up documentation as stuff was developed and tested I, for one, would not be interested in paying extra hours for it, it's going to be trash for all sorts of reasons.
Admin
Don't forget that the company almost certainly asked for some changes they they viewed as "clarifications" during the course of the project. If the company goes to the letter of the contract for the documentation, the developers might go to the letter of the contract for all of the changes. Once this mutually assured destruction cycle starts, the only way out of it is to pretend the past never occurred and pay for what you want from this point on.
Admin
|The worth of a comment is proportional to the (perceived) complexity of the code it |comments on. The comments picked in the article seem worthless and even a joke, which |could mean that the code is utterly self-explanatory. I'm undecided about this WTF due to |a lack of code in the article.
Yup--I consider comments something of a code smell. If you need them the code isn't self-explanatory enough. Occasionally you need to comment the reason for a choice.
Admin
I'll repeat the Standard Operational Response to your axiom here.
Comments are not meant to describe what the code does. As you say, the code (plus naming conventions, etc) should suffice for that.
Comments are meant to describe [B]how the code functions semantically[B]. And also [B]how the code implements the business domain[B].
That is why writing comments is an art, a useful art, an indispensible art.
You can't usefully hack comments, any more than you can usefully hack code, if you're aiming for a quality level above liquid sewage.
Admin
Comments and unit tests follow the same anti pattern. First, a subset of people don't use them. Then, when coerced, the same subset manages to do them in a way that provides absolutely zero benefit. Finally, the subset blames the time wasting on those that insisted they do them.
Admin
Yes, unfortunately, whenever I've heard people parroting "good code is self documenting" every thirty seconds they turn out to be people who write incredibly awful code.
Which is a shame, because the statement is sort of true, although as Sole Purpose of Visit said, there are real reasons to put helpful comments. I'd add to his list where you are having to deal with legacy shit/third party controls/ APIs over which you have little control and have to do "weird" stuff or where their properties and methods have misleading names.
I also use comments in place of source control, where there isn't a system in place (no, really, that's still a problem!). Last time I had that, the idiot I was working with used to delete my tracking comments because he saw them as "unprofessional".
Admin
So, I see this argument come up fairly often, and I think it has a really subtle but really important flaw. Whether something is "self-explanatory" can depend on the reader's familiarity with the context it's in. And there's often a lot more context than we're familiar with. Make a code change to fix a bug? That's contextual information someone else reading the code won't have!
So, yes, strive to make your code as self-documenting as possible. Then document it anyway. Not only do you avoid that problem - of someone, maybe yourself six months from now, seeing the same code without the same context - it's a good way to check how clear your code is. If you can't write good comments, then it's probably not as clear as you think. If you can, then you've already written them, so leave them in.
(C#'s
<remarks>or Java's@apiNotedocumentation tags work wonders for this.)Admin
I agree
Admin
Another thing to consider is that there are many languages and development enviroments out there and not all are equal. A C++ function like int DoSomething(int argC, int argV) written in visual studio is extremely self documenting. That same function written in Javascript in notepad++ not so much.
When ever you have to deal with languges that don't have clear and distinct typing and yet require inputs to be just right for the internal logic to work comments are indispensible.
Admin
I think comments that explain code can be useful, because they can sum stuff up. Can I read through these 10 lines of code and see that it calculates a sum of various columns in a table? Sure. But if I can just read one line of comment and know that too, that's nice
Admin
In my experience this was the Microsoft C# .NET API documentation for many years (it has improved A LOT in the past years, i.e. when they open sourced it). And C++ Boost often. Or any C library API.
Admin
Nothing could be further from the truth. It's not perfect but one thing Microsoft is know for doing better than most if not all other vendors (for example Apple and Oracle) is documentation.
Admin
I agree with commenting things even if they're named and formatted properly. All you need to do is read your own code from a few months ago and you'll realize how important it is.
Admin
We've all read self-documenting code - but it included the string "Hello World".
Admin
A lot of people do comments wrong, including most people who think they're worthless.
A good comment tells you the why of the something being done. No matter how self-explanatory your code is, it's difficult to have it indicate the source of the requirement of a particular part of the program. Programs don't just spring into existence wholly formed. There's usually a chain of events and probably discussions. There may be standards, policies, contracts involved, which can easily be entirely forgotten in a comment-free program.
Note that it's not sufficient to simply state that source and feel that the context of the comment will indicate exactly what part of the code was required by that source, as it's nigh guaranteed that sooner or later, someone will go in and change the code without updating the comment, especially if the comment isn't clear exactly to what it's referring.
Admin
I saw it put well on this forum before: The code explains what it DOES. The comment explains what it's SUPPOSED to do.
The two are often different, as seen on this very site. ;)
Also, I think most developers have been trying to figure out what a piece of code does and cursing the idiot who wrote it, only to realize THEY wrote it. Code is self-explanatory when you are writing it, but a year later, when you are totally divorced from the train of thoughts that led to it, it might not be.