Welcome to the Lounge

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

My God. There are really programmers who think it's okay to write S/370 assembler without comments? I thought I'd read the whole Book of Engineering Sins, but I must have missed that page.

I can only offer one comparable instance of evil, though in this case it was an evil development tool: a microassembler for a highly unusual synchronous communications device. This lashup had five parallel processors on it: an ALU, a microsequencer, a memory access controller, and two bus bridges. Its 48-bit-wide instructions had to address all five at once, with...interesting constraints and side effects regarding timing and conditional operation.

I was handed this device, the documentation for it (which was sketchy), and the existing microprogram for it, and told to make a range of enhancements to it. Imagine my surprise when I opened up that microprogram -- approximately 4000 instructions long -- and discovered that it contained not one single comment.

Needless to say, I immediately looked up the previous maintainer, who was overjoyed that the responsibility had passed from him, and inquired about the lack of commentary. He then told me the most incredible thing I've ever been told about a development tool:

It was true. I hadn't had any idea before he said so.

I spent the next six weeks, over the strenuous objections of my management, writing a new microassembler for the damned thing. Three years later, when the responsibility for the device passed from me to a young successor, the program was fully commented.

Fran Porretto wrote:

I spent the next six weeks, over the strenuous objections of my management, writing a new microassembler for the damned thing.

Fran Porretto wrote:

There are really programmers who think it's okay to write S/370 assembler without comments?