Welcome to the Lounge

"Just because your mother slept with her brother doesn't mean the rest of us will agree it's a good idea."

Maximilien wrote:

Stupid/Verbose/Out of sync comments are worse than no comments.

public StockItem FindTheStockItemWithTheEarliestSellByDateThatIsEitherOfTheTypePassedOrOneOfTheGenericTypesSimilarToThatTypeThatIsAcceptableByTheCustomer(StockType stockType, Customer customer, Date dateToCheck)
{
}

/*
  Find the stock item with the earliest sel by date that is either of the type passed, or one of the generic types, similar to that type, that is acceptable by the customer
*/
public StockItem FindStock((StockType stockType, Customer customer, Date dateToCheck)
{

}

Maximilien wrote:

Stupid/Verbose/Out of sync comments are worse than no comments.

ahmed zahmed wrote:

...is as important as well architected and well implemented code.

_Maxxx_ wrote:

because it is self documenting, all methods are small and have single
functionality

_Maxxx_ wrote:

and any business documentation should be provided by the specification and not
the code.

Ravi Bhavnani wrote:

The nice thing about using automated API documentation generation tools like JavaDoc[^] and Sandcastle[^] and NDoc[^] is that they allowa a single source of comments (i.e. in the code) to be maintained.  This makes it easy to ensure that the generated docs are up-to-date and reduces the risk of introducing miscommunication between the author of the comments and another team that may be tasked with producing the documentation.

// Save the customer.
product.Save();

// i is the index.
int i = 0;

// See mail QQ (it wasn't actually QQ, they were two other initials).
this.DoSomething();

// What I mean to say in the following section is that Frodo takes his ring to Mount Doom to destroy it, but is attacked by the creature we know as Gollum.
(actual text) jkfhadj.kbvadulvkb;jlbn av,lnvaduk aa;vn ;ub jb kgbfleukg vbvs
dfgg afgh;a jafhuhg jdbakjbfjgdfgbukfha afdgfhfdh g fdgfadfgafg fgafdgarerthgaer9df/d.kj fgjdakh
adfg f8oyfagh ahg hgafoihlawr;ahbnfbjn afad;jkh gfnadjkh89fadyg

public class Naerling : Lazy<Person>{
    public void DoWork(){ throw new NotImplementedException(); }
}

There are a number of interesting aspects to the "comment / don't comment" debate. Let's dispose of the easy ones first:

1. Trivial comments. Lord, let me never again see:

i++; // Increment I by one.

...in a subordinate's code.

2. Comments about technique or mechanics. If your code comments are about technology rather than "business logic," they're probably unnecessary. Yes, it's interesting beyond words that you chose a Shell-Metzner sort over the easier to use Quicksort, but "beyond words" is probably where it belongs. Matters of programming technique are easily looked up online or in reference books.

3. Drift, Type 1. As with external documentation, comments can drift away from the code to which they're attached. That doesn't mean the code shouldn't be commented; it merely means that the comments should be maintained along with the code -- and to fail to do so is to fail as a programmer.

Now for the not-so-easy ones:

4. Drift, Type 2. If there has been a significant alteration in the application, such that the earlier "business logic" no longer applies, it will probably -- let's hope, anyway -- have been captured in a revision of a requirements specification. That, of course, will compel significant alterations to the code...but the new "business logic," as instantiated in the code, should still be annotated in comments unless that logic is so trivial as to require no comment whatsoever (e.g., profit = price - aggregate cost of production).

5. Posterity. You, the developer, are prone to think only of your own needs and desires while you're in the process of developing your application. But it's even money or better that you won't be the last programmer to work on that program -- and it's six-five and pick 'em that your successor:

• Won't be nearly as conversant with the application's "business logic" as you've come to be;
  
• Won't agree with your technique or your coding style in all particulars;
  
• Will be under serious deadline pressure and could use all the help he can get!
  

Actually, it can be even worse than that: the guy who picks up your program and tries to fix or modify it could well be very, very junior, and thus exposed to all sorts of hazards you, the senior developer, are (relatively) well protected from. Uncommented code can be a nightmare for such a maintenance programmer, especially as the most junior sorts typically get the dirtiest jobs and are utterly unprepared by their "educations" for the challenges of practical software engineering. There's plenty of room in our trade for human kindness to your unnamed, unseen inheritors.

6. Polymorphism has its own challenges. If you employ an oblect-oriented language that's liberal about polymorphism, you're likely to write methods that have the same name but do appreciably different things. These divergences should be commented, and carefully. Likewise, we tend to be blase about the reuse of names for variables at different levels of scope. This isn't good practice, but most of us fall prey to it. If you're going to do so, then accept the obligation to comment those variations, as well, with appropriate mention of the scoping differences.

7. Low-level languages. Don't even dream about writing C, assembler, or (God help us) microcode without comments!

Just now, this subject is of unusual importance to me, as I'm struggling to convert a 250,000 line C# (gag, retch, barf) program from one point of application to another, vaguely related one for which it was never intended -- no, I wasn't given any choice in the matter -- and the damned thing was written by a committee of mutually hostile developers, not one of whom is still available to support it, and it doesn't have a single line of commentary in it.

Please, please: Don't do this to others. God will have harsh words for you at the Bar of Judgment.

BALR RTN, PRINT

BALR 8, PRINT