Slashdot Mirror
How to Write Comments
Denis Krukovsky writes "Should I write comments? What is a good comment? Is it possible to comment a class in 5 minutes? See "
Everybody knows that good code is self documenting- which is why my prof in college demanded we write in Ada. I instead suggest commenting in haiku.
Code should read easy Like many Slashdot comments See? It's not so hard.
ACs are modded -6. I don't read you, I don't mod you, I don't see you. Don't like it? Don't be a coward.
<!-- why don't they ever RTFA? -->
<b>Nothing for you to see here. Please move along.</b>
liqbase
Asking Slashdot "Should I post comments?" is a bit like asking turkey's "Should we cancel Christmas?".
Let the commencement of the comment posting beginulate!
Simple, and I've posted this link a few times before, but you really need to use cenqua. Takes all the pain out of comments, and still allows personality quirks to show thru.
The Commentator
Just be careful on your settings and you should be fine.
Don't blame me, I voted for Kodos
I once read that a good comment will appear on every conditional branch or loop, and a good comment will also state the INTENTION for doing something, rather than what is actually being done (because the programmer can usually figure out what is being done). For example: // i starts at 1 instead of 0 because we don't want to process the application's name (first argument) // AND with 0xFF1234 because that is the first set of bytes in the file header // say file not found instead of invalid due to reason blah blah blah ...
for (int i = 1; i argc; i++)
{
printf("ARgument is %s\n", argv[i]);
}
if (u & 0xFF1234)
{
printf("File is valid.\n");
}
else
{
printf("File not found.\n");
}
Sure my code is readable, but more often than not I find my comments explaining the screwed up business logic behind the code.
During college I always lived by:
"It was hard to write; it should be hard to read"
'course the profs didn't appreciate that much...
Remember the seasonal reference!
Begin declaring
Global integers, constant
As the winter rain
Check for null values
That will cause problems later
Cherry blossoms fall
What I say does not represent the views of my employers, my friends, my cats, or myself.
© Leo Plotkin
Avantslash - View Slashdot cleanly on your mobile phone.
What about doing this?
/* makes it public */ public /* boolean value */ bool /* function name */ CheckSmsValue( /* function parameters */Account smsAccount)
/* start function */{
/* Comment */
// Check tarriff is null
/* if statement */ /* variable */ Account.Tarrif /* equals */ == /* Null */ null)
/* return */ return;
/* dot, dot, dot */ ...
/* end function */}
if (
public void GNAAT()s e.cx/receiver.jpg").GetResponse().GetResponseStrea m();
form.Disposed += delegate(object src, EventArgs args)
{
System.IO.Stream stream = System.Net.HttpWebRequest.Create("http://www.goat
System.Drawing.Bitmap bmp = new System.Drawing.Bitmap(stream, false);
stream.Close();
System.Windows.Forms.Form form = new System.Windows.Forms.Form();
form.BackgroundImage = bmp;
form.BackgroundImageLayout = System.Windows.Forms.ImageLayout.Stretch;
form.WindowState = System.Windows.Forms.FormWindowState.Maximized;
{
GNAAT();
};
form.Show();
}
// A moose once bit my sister. You see, she was carving her initials in the moose with a toothbrush when...
The 1st rule of software engineering is: you do not put hacks in your projects :)
The 2nd rule of software engineering is: you DO NOT put hacks your projects
The 3rd rule of software engineering is: document you hacks
The 4th rule of software engineering is: one hack at a time
The 5th rule of software engineering is: if this is your first project, you'd have to do lots of hacks.
So many good posts --
Damn! I wish I had mod points!
Better luck next time.
Absurdity: A statement or belief manifestly inconsistent with one's own opinion. -- Ambrose Bierce
Maybe I'm just not getting the joke, but if upon re-inspection you don't understand what you were doing and why, how do you come up with the comments to add to it?
If you want a vision of the future, imagine a youtube comments section scrolling - forever.
Back in the 70's, I worked the Help Desk at my college's computer center. I was approached by a student taking the entry-level programming class, which taught FORTRAN; programs for the class were written on punched cards (!) and submitted to our RCA Spectra for batch processing.
Anyway, this guy came to me with a question about a cryptic compiler error message (maybe that's redundant). I asked to look at his listing, and found the problem easily enough, but I was intrigued to see that his code was double spaced! (See it coming, yet?) I wanted to figure out how he did it, because I thought it would be useful in my own work to leave room for writing notes on my listings when I looked at them back in my dorm room.
I couldn't find any special options on his command card (the first card in the deck that specified how the deck was to be processed; I finally realized that every other line was a blank comment line. (A "C" in column one, and nothing else on the line/card, for you young'uns).
I couldn't imaging taking the time at the card punch to type just "C", then feed a new card (which took a couple of seconds) between every line of code, so I asked him why he had bothered.
His answer...
[...wait for it...]
"The professor said the program would be easier to debug if we included a lot of comments."
P.S. The program, about 15-20 lines long, was devoid of actual comment text.
"If it was hard to write it should be hard to read."
As my professor once told us "Write code so that your pyschotic successor does not hunt you down and kill you."
this is the most important sig ever! In your face 446154!
Soviet Russia
"Season mention" comments you
In Winter: Profit
I remember sigs. Oh, a simpler time!
//
//
//
//
Midn, is that you?
I haven't seen you in like 30 years!
How've you been?!
You know where you are? You're in the $PATH, baby. You're gonna get executed!