Code comments: How do you comment your code?

[OriginalGriff]

Mark Wallace wrote:

You keep the crayon within the lines?

Spraycan and a stencil - much easier!

All those who believe in psycho kinesis, raise my hand.

[Nagy Vilmos]

[camp] Ooh! Get you! [/camp]

---

Panic, Chaos, Destruction. My work here is done.

[Nagy Vilmos]

I find anybody who was coding [professionally] more than 15-20 years ago is pretty good on pre-commenting. It's the low order primates that cause me grief.

---

Panic, Chaos, Destruction. My work here is done.

[realJSOP]

Regions aren't an adequate replacement for comments. I comment the code profusely, and in the event that there is a sufficiently complex implementation, I write a separate "How It Works" document in Word, and make check that document into source control with the rest of the project.

.45 ACP - because shooting twice is just silly
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997
-----
"The staggering layers of obscenity in your statement make it a work of art on so many levels." - J. Jystad, 2001

[Dalek Dave]

John Simmons / outlaw programmer wrote:

I comment the code profusely, and in the event that there is a sufficiently complex implementation, I write a separate "How It Works" document in Word, and make check that document into source control with the rest of the project.

That seems very concise, but I, unfortunately, have never written anything so complex as to warrent that. However, I shall bear it in mind if ever I do.

------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce

[dan sh]

I prefer this: 1. Group related methods in a region. 2. XML style commenting for the methods. You can also keep each method in a region of its own. This removes the scrolling required in case of huge file. 3. If the method is huge, break that into regions as well (better to split it into smaller methods). 4. Every important line/block of code should have a comment before stating what it is doing. 5. In case there are nested if/else, keep footer comments to make sure you don't have to wonder where did you missed that closing "}". 6. In case you have written some "work around" (read weird stuff), do not forget to mention the reason for it or else the other guy would mess that curse you forever. 7. In the end, read the entire file and get rid of excessive commenting.

50-50-90 rule: Anytime I have a 50-50 chance of getting something right, there's a 90% probability I'll get it wrong...!!

[Mark_Wallace]

Nelek wrote:

editing function names (search and replace) with some cryptic / not easy names

Has anyone ever asked you what Function FormatCDrive() actually does?

I wanna be a eunuchs developer! Pass me a bread knife!

[Lost User]

Join the cool kids - Come fold with us[^]

[Dalek Dave]

hmm, let me just try th

------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce

[Ravi Bhavnani]

I've been using a simple yet effective rule for writing comments for decades:

• Remove all code except for block boundaries (i.e. everything except stuff in conditional expressions and opening and closing curly braces).
• Do the remaining comments and "code shell" represent the psuedocode fairly accurately?
• If yes, you're done. Else, you need more comments.

It's amazing how well this rule works.  Without conciously trying, applying this rule caused me to move from writing few long-winded PhD thesis comment blocks to several small one-line phrases that increase readability many fold. /ravi

My new year resolution: 2048 x 1536 Home | Articles | My .NET bits | Freeware ravib(at)ravib(dot)com

[Single Step Debugger]

I don’t comment my code, even the most complex parts. Nobody pays me for comments, they want functionality and reliability. What?

The narrow specialist in the broad sense of the word is a complete idiot in the narrow sense of the word. Advertise here – minimum three posts per day are guaranteed.

[realJSOP]

I do it mainly for myself so that I can remember the whats-and-whys more than anything else, and to provide a foundation of knowledge regarding the system, and the reasons for its existence.

.45 ACP - because shooting twice is just silly
-----
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997
-----
"The staggering layers of obscenity in your statement make it a work of art on so many levels." - J. Jystad, 2001

[Dalek Dave]

And you want to keep the contract, right?

------------------------------------ No Good Deed Goes Unpunished Clare Boothe Luce

[dan sh]

John Simmons / outlaw programmer wrote:

I write a separate "How It Works" document in Word

Cool! I also maintain a notepad file (just for myself) containing why I wrote the code block that way. I also try to maintain what I had tried and why it failed so that I don't end up doing same thing again.

50-50-90 rule: Anytime I have a 50-50 chance of getting something right, there's a 90% probability I'll get it wrong...!!

[Single Step Debugger]

Dalek Dave wrote:

And you want to keep the contract, right?

I definitely do, but this doesn’t involve losing hours and hours in writing useless comments.

/*
* This function returns the next document in the sequence!
*This is an extremely useful comment! It makes me feel real professional!
*My Mother will be real proud with me! And I’m going to use an automates toll to generate an utterly
*useless documentation for this application.
*
*/
LPDISPATCH CDocumentation::GetTheNextDocumentWithPreview()
{
iDispatch->GetNextDocument(true);
}

The narrow specialist in the broad sense of the word is a complete idiot in the narrow sense of the word. Advertise here – minimum three posts per day are guaranteed.

[Mark_Wallace]

Trollslayer wrote:

CalcNumber firstNumber = CalcNumber.create(3);
CalcNumber secondNumber = CalcNumber.create(2);
CalcNumber nutting = CalcNumber.create(0);

figureToPost = firstNumber + secondNumber;
figureToPost += nutting;

returnString = figureToPost.ToString();
fullPoint = ".";

String.Concat(returnString, fullPoint);

return returnString;

See? Works every time! Your pseudocode helped me construct it easily!

I wanna be a eunuchs developer! Pass me a bread knife!

[Daniel Grunwald]

I comment the public API of my classes using XML documentation comments. Though often it's obvious what a method is doing given its name, so I only fill in a short summary and leave out the parameters/return value stuff. I do use regions to group methods in large classes. I think it's a sign that the class is too large, but that's unavoidable in some frameworks (e.g. when writing WPF controls). For the implementation inside methods, I usually don't write any comments initially. If I have to change the code to fix bugs, I'll add comments why the fix was necessary (unless the bug was just some kind of typo). Basically, you shouldn't need comments to see what the code is doing. Inline comments should explain why the code is doing it, but only if that isn't obvious given the method's name/documentation. I also make use heavy use of invariants, so my Debug.Assert statements can be seen as a kind of comment.

[Joe Woodbury]

I rarely do. I've found comments are pretty useless and mostly good for giving people warm and fuzzies. Instead, I use very descriptive names for functions, methods, classes and variables and keep my code as simple as possible. Same with my coworkers.

Harvey Saayman wrote:

(usually explaining why your in a specific part of an if statement)

See, that's idiotic. If your "if" statement is written so poorly that you don't know why you're in it, your programming technique sucks. Some code I just wrote:

...
} while (m_curSelection != orgSelection && !m_pItems[m_curSelection].IsSelectable());

No comment is going to make that more clear.

[Marc Clifton]

Harvey Saayman wrote:

I've decided to make use of regions

I despise regions!

Harvey Saayman wrote:

So how do you comment your code?

Don't tell me what the code does (I can figure that out quickly enough) tell me WHY it does it, and what the decisions were to lead up to that implementation. That brings a lot more understanding, IMO. Marc

Will work for food. Interacx

I'm not overthinking the problem, I just felt like I needed a small, unimportant, uninteresting rant! - Martin Hart Turner

[Gary Wheeler]

Marc Clifton wrote:

I despise regions!

Unfortunately, I think most people think of regions as a documentation mechanism, rather than an editing tool. I use them to make the outlining more useful. With regions, I can more quickly collapse parts of the code out of the way so I can concentrate on the other bits.

Software Zen: delete this;