Comments

Please compose all posts in Emacs.

Moderators: phlip, Moderators General, Prelates

User avatar
Dingbats
Posts: 921
Joined: Tue Mar 20, 2007 12:46 pm UTC
Location: Sweden
Contact:

Comments

Postby Dingbats » Wed Nov 28, 2007 3:53 pm UTC

This may be on the far side of pointless, but what the hell :P

I always start my comments with a capital and end with a period, and no space between the comment delimiter and the text. That makes it all look nice and tidy.

Code: Select all

#Like this.

User avatar
crazyjimbo
Posts: 887
Joined: Fri Apr 20, 2007 11:45 pm UTC
Location: Durham, England
Contact:

Re: Comments

Postby crazyjimbo » Wed Nov 28, 2007 3:55 pm UTC

I can't stand not putting a space between the comment symbol and the beginning of the sentence. But yes, capitals and full punctuation are nice, although I wouldn't bother with a full stop for short comments.

User avatar
pieaholicx
The cake is a lie!
Posts: 531
Joined: Mon Oct 22, 2007 12:51 pm UTC
Contact:

Re: Comments

Postby pieaholicx » Wed Nov 28, 2007 3:58 pm UTC

It really depends on the comment, though for styling them I usually put a space between the marker and the comment. My usual stylings:

Code: Select all

# Comment here
; Comment
// Comment
/* Multiple
 * Line
 * Comment
 */


Well, the multiple line doesn't really work, but I put them at the same spacing so the asterisks are a line straight down.
It's okay, I'm Chaotic Neutral. I can kill him over the loot.
Overexposure to pieaholicx may, in semi-rare cases, emancipate dental fillings, crowns, tooth enamel, and teeth.

Robin S
Posts: 3579
Joined: Wed Jun 27, 2007 7:02 pm UTC
Location: London, UK
Contact:

Re: Comments

Postby Robin S » Wed Nov 28, 2007 3:59 pm UTC

I have essentially the same protocol for comments as for instant messages: beginning a comment with a capital letter is not necessary; new lines for clauses within a sentence or between sentences are acceptable, in which case appropriate punctuation is not necessary. Otherwise, ordinary grammar, including punctuation.
This is a placeholder until I think of something more creative to put here.

Sana
Posts: 123
Joined: Wed Sep 26, 2007 3:53 am UTC

Re: Comments

Postby Sana » Wed Nov 28, 2007 7:48 pm UTC

I tend to always type with proper conventions, and my comments don't break that personal tradition. I always put a space between the comment character and the comment.

Code: Select all

/* My multi-line comments look like this.
­ * I start each subsequent line like this.
­ * I space it so the asterisks line up with the asterisk on the first line. */

EvanED
Posts: 4331
Joined: Mon Aug 07, 2006 6:28 am UTC
Location: Madison, WI
Contact:

Re: Comments

Postby EvanED » Wed Nov 28, 2007 7:54 pm UTC

Always a space between the start-of-comment indicator and the first word. Short comments don't have to follow more rules than "be helpful"; longer comments should be in correct English. (Sentences, or at least fragments (like my first "sentence" in this post), capitals, etc.) I shun the comments. I fail to see why

Code: Select all

// Blah blah blah
// blah blah. Blah
// blah.

is not better than

Code: Select all

/* Blah blah blah
 * blah blah. Blah
 * blah.
 */

and I like the "this is continuing a comment" * at the beginning of the lines.

User avatar
Citizen K
Posts: 103
Joined: Fri Sep 21, 2007 11:42 am UTC
Location: Maryland

Re: Comments

Postby Citizen K » Thu Nov 29, 2007 8:09 pm UTC

I follow the same rules for comments as powerpoint bullets.
If it's a complete sentence or a paragraph, it gets capitalization and punctuation. Otherwise, not. But consistency and parallelism are most critical for legibility.
Beware the cows! Not all milk is enriched.

zenten
Posts: 3799
Joined: Fri Jun 22, 2007 7:42 am UTC
Location: Ottawa, Canada

Re: Comments

Postby zenten » Thu Nov 29, 2007 8:35 pm UTC

I tend to write it like this:

Code: Select all

// Here is a single line comment, or at least a few short lines.

/*
Here is a comment that is more like a paragraph or more writing.  Although I'm not doing that here, because I don't have that much to say.
*/

User avatar
Kizyr
Posts: 2070
Joined: Wed Nov 15, 2006 4:16 am UTC
Location: Virginia
Contact:

Re: Comments

Postby Kizyr » Thu Nov 29, 2007 11:44 pm UTC

If I'm commenting out code, then I'll do something similar as you. Say:

Code: Select all

*data temp;
*   set temp;
*   do i = 1 to 10;
*      output;
*   end;
*run;


If I'm doing descriptive comments, though, I'll always put a space between the comment-mark and the comments, continue comments on the next line with indentation, etc. Punctuation is optional; I'll usually only use it in long comments that need multiple sentences. Say:

Code: Select all

/* Main directory of program */
   %let main_path = C:\Temp;

/* Filenames to read in. For the FY2008 estimation,
   the FY2007 files were used. */
   %let input_files = something1.txt something2.txt;


I'm not picky about how other people do comments, though, so long as it's easy-to-read and consistent. ...and they actually comment to begin with. KF
~Kizyr
Image

Rysto
Posts: 1460
Joined: Wed Mar 21, 2007 4:07 am UTC

Re: Comments

Postby Rysto » Fri Nov 30, 2007 12:59 am UTC

If I'm commenting out out code, I do:

#if 0
if(something)
....
#endif

zenten
Posts: 3799
Joined: Fri Jun 22, 2007 7:42 am UTC
Location: Ottawa, Canada

Re: Comments

Postby zenten » Fri Nov 30, 2007 1:12 am UTC

Rysto wrote:If I'm commenting out out code, I do:

#if 0
if(something)
....
#endif


Ow.

Rysto
Posts: 1460
Joined: Wed Mar 21, 2007 4:07 am UTC

Re: Comments

Postby Rysto » Fri Nov 30, 2007 1:21 am UTC

You never have to worry about nested comments when you use #if 0. It really is the best way to go.

User avatar
JayDee
Posts: 3620
Joined: Sat Nov 10, 2007 3:13 am UTC
Location: Most livable city in the world.
Contact:

Re: Comments

Postby JayDee » Fri Nov 30, 2007 1:53 am UTC

wouldn't you still have the same problem if you had nested #endif statments? I'm assuming that'd only happen when you comment out a section of code that already contains a commented section of code, but still.

Oh, and:

Code: Select all

30 REM THIS LINE IS A COMMENT

Rysto
Posts: 1460
Joined: Wed Mar 21, 2007 4:07 am UTC

Re: Comments

Postby Rysto » Fri Nov 30, 2007 2:06 am UTC

JayDee wrote:wouldn't you still have the same problem if you had nested #endif statments?

No, #if/#endif nest properly.

btilly
Posts: 1877
Joined: Tue Nov 06, 2007 7:08 pm UTC

Re: Comments

Postby btilly » Fri Nov 30, 2007 3:25 am UTC

Rysto wrote:If I'm commenting out out code, I do:

#if 0
if(something)
....
#endif

Thereby leading to much confusion when the next guy finds some of the commented out code, thinks it is live code, finds what they want to change, then tries to fix it.

You are evil, and I'm glad I don't work with you.

About the original question, I use proper English in my comments. Being a decent typist, I don't even have to think about it.

About comments in general, there are a lot of subtle issues on commenting. If you haven't read it, go read what Code Complete says about comments. If you are too lazy to do that, then keep the following facts in mind:

- About 1 line in 10 when initially written has a bug. (This is a general cognitive error rate for people.)
- Bugs in code get fixed.
- Bugs in comments don't.

The result? If comments and code disagree, trust the code. Therefore rather than trying to make code clear by adding comments, you should make code clear to the extent possible by making code clear. That means good variable names, good use of subroutines, etc, etc, etc. There are still things that you should comment, but it will happen less often.

For a discussion of my personal style, see http://www.perlmonks.org/?node_id=65153. (My style has evolved since then, for instance I'm less likely to abbreviate variable names, but what I wrote in that discussion is still largely true.)
Some of us exist to find out what can and can't be done.

Others exist to hold the beer.

Rysto
Posts: 1460
Joined: Wed Mar 21, 2007 4:07 am UTC

Re: Comments

Postby Rysto » Fri Nov 30, 2007 3:27 am UTC

Commented-out code of any kind should never make it back into the repository anyway. And any self-respecting IDE recognizes #if 0 and will format the code as a comment anyway.

btilly
Posts: 1877
Joined: Tue Nov 06, 2007 7:08 pm UTC

Re: Comments

Postby btilly » Fri Nov 30, 2007 3:42 am UTC

Rysto wrote:Commented-out code of any kind should never make it back into the repository anyway. And any self-respecting IDE recognizes #if 0 and will format the code as a comment anyway.

I've seen plenty of commented out code that made it back to a repository. Why? Because the person who commented it out expects it to be uncommented again sometime. I'll agree that this is often done when it shouldn't be. But sometimes it makes sense.

For instance I might leave in some commented out debugging statements in languages without preprocessors. Some day I'll want to see what queries are hitting the database. Right now I don't.

About syntax highlighting. Yes it is useful and I use it. But I've seen incremental highlighting get confused enough times that I don't want to depend on it.
Some of us exist to find out what can and can't be done.

Others exist to hold the beer.

Rysto
Posts: 1460
Joined: Wed Mar 21, 2007 4:07 am UTC

Re: Comments

Postby Rysto » Fri Nov 30, 2007 4:05 am UTC

If a language doesn't have a preprocessor then it doesn't have #if 0, does it?

btilly
Posts: 1877
Joined: Tue Nov 06, 2007 7:08 pm UTC

Re: Comments

Postby btilly » Fri Nov 30, 2007 4:23 am UTC

Rysto wrote:If a language doesn't have a preprocessor then it doesn't have #if 0, does it?


It may still have if (0) {...}. (Which frequently is not recognized by syntax highlighting.) Or a multi-line quoting mechanism. Or some other trick that can be abused. (For instance Perl's perldoc mechanism can be used for commenting out blocks of code.)

In all cases it is easy in a decent editor to take a block of code and comment it out in a way that screams out that has been commented out. And then nobody will accidentally think it is live.
Some of us exist to find out what can and can't be done.

Others exist to hold the beer.

Rysto
Posts: 1460
Joined: Wed Mar 21, 2007 4:07 am UTC

Re: Comments

Postby Rysto » Fri Nov 30, 2007 4:29 am UTC

There's a big difference between #if 0 and if(0).

btilly
Posts: 1877
Joined: Tue Nov 06, 2007 7:08 pm UTC

Re: Comments

Postby btilly » Fri Nov 30, 2007 4:56 am UTC

Rysto wrote:There's a big difference between #if 0 and if(0).


Sure, there are differences. Starting with the fact that one uses the preprocessor, the other doesn't.

However there are a lot of similarities. In particular there is the huge similarity that both mechanisms make a block of code not be executed, which means that they can be used to "comment out" blocks of code. (Only the preprocessor version will comment out blocks of code with illegal constructs though.)

Incidentally if the difference you were thinking of is that one always operates at runtime and the other at compile time, then you're wrong. Depending on the language and compiler, the "runtime" version can get optimized away at compile time.
Some of us exist to find out what can and can't be done.

Others exist to hold the beer.

Rysto
Posts: 1460
Joined: Wed Mar 21, 2007 4:07 am UTC

Re: Comments

Postby Rysto » Fri Nov 30, 2007 5:18 am UTC

The biggest difference is that preprocessor directives are not part of the syntax of the language, while if(0) is. A preprocessor directive is far more obvious than if(0).

zenten
Posts: 3799
Joined: Fri Jun 22, 2007 7:42 am UTC
Location: Ottawa, Canada

Re: Comments

Postby zenten » Fri Nov 30, 2007 3:19 pm UTC

Rysto wrote:You never have to worry about nested comments when you use #if 0. It really is the best way to go.


Why would I have to worry about nested comments?

Rysto wrote:The biggest difference is that preprocessor directives are not part of the syntax of the language, while if(0) is. A preprocessor directive is far more obvious than if(0).


I would say that neither are terribly obvious.
Last edited by zenten on Fri Nov 30, 2007 3:21 pm UTC, edited 1 time in total.

User avatar
Tei
Posts: 63
Joined: Fri Nov 30, 2007 2:58 pm UTC

Re: Comments

Postby Tei » Fri Nov 30, 2007 3:43 pm UTC

Compiled code:

Code: Select all


if  (0) {

} else {

}



For optional code, that may one day be readed from a variable, but that now i want to manually adjust, with my hands on the dirty code.

--

Code: Select all

/*  Explanation comment */


Long or one line comment. The official comments, with full logic. Complete phrases.

--

Code: Select all


//TODO: optimize the next call
foo();

bar();//this can break the buffer, but is needed here.



// is the king of small *dirty* comments.

--

Code: Select all


#ifder __BOGUS__


#endif



Proper optional blocks for ...welll optional compiling.

--

EvanED
Posts: 4331
Joined: Mon Aug 07, 2006 6:28 am UTC
Location: Madison, WI
Contact:

Re: Comments

Postby EvanED » Fri Nov 30, 2007 4:03 pm UTC

zenten wrote:
Rysto wrote:You never have to worry about nested comments when you use #if 0. It really is the best way to go.


Why would I have to worry about nested comments?

If you are trying to comment out code that has /* */ in it (using /* */ comments), you'll quickly discover why you have to worry about nested comments.

(This is why I [almost] never use /* */ comments; I prefer them to #if 0 for commenting out code as editors are much better about correctly highlighting comments then inactive code. I mean, I've worked on code in VS2005 where we had to turn off the greying out of inactive code because, since we had essentially the equivalent of -D commands elsewhere, VS2005 was greying out the wrong blocks.)

Dongorath
Posts: 93
Joined: Tue Oct 16, 2007 1:17 pm UTC

Re: Comments

Postby Dongorath » Fri Nov 30, 2007 4:15 pm UTC

Code: Select all

using blah.blah.blah;
#if XLSIO
using Syncfusion.XlsIO;
#endif

[...]

// This function do something (insert explanation here)
protected virtual void myFun(string arg)
{
    // OK, let's the fun begin, I must do this
    // and that...
    // blah blah blah
    /* If I use multiline comment block,
     * I align the stars
     * But I use few of them... Don't know why, though...
     */
    [some code here]

    // The following do something tricky (explanation here)
    // The definition of tricky varies from "it's natural to me, but 80% of my coworkers don't understand" to "eh ! I think that's pretty clever even for me"
    [some "tricky" code]

#if XLSIO
    [code using the Syncfusion library
#endif

    if (false)
    {
        [code that the client don't want today, but I'm pretty sure they'll beg me for it tomorrow]
    }
}


I scarcely use the /* */ comments, and almost never // comments at end of lines. Correct phrases with full punctuation. #if-#endif blocks around blocks that depend on a library that might not be present in the project (I work on 3-layered applications, the first two being supposedly generic, the third is specific to the client).

PS : it's C#.

User avatar
Number
Posts: 63
Joined: Thu Aug 02, 2007 5:42 am UTC
Location: Earth. supposedly

Re: Comments

Postby Number » Sun Dec 02, 2007 1:55 am UTC

if(0) can be used for things other than commenting, such as

Code: Select all

char *p;
switch (n)
{
case 1:
    p = "one";
    if (0)
case 2:
    p = "two";
    if (0)
case 3:
    p = "three";
    printf("%s", p);
    break;
}

You might confuse the person/IDE reading your code. Which, according to the article I took this from, should help promote your job security :D.

Anyway...
// This is a short comment, which is probably < 5 lines long.
// this is really brief

/* Sometimes I line up the stars; it depends on my mood.
*/

During debugging, in-line comments can appear (doSomething(x, /*y*/ z);)
You live and learn. At any rate, you live.

User avatar
b.i.o
Green is the loneliest number
Posts: 2519
Joined: Fri Jul 27, 2007 4:38 pm UTC
Location: Hong Kong

Re: Comments

Postby b.i.o » Sun Dec 02, 2007 2:48 am UTC

I use // comments for one or two lines, and /* */ comments for comments longer than that. I also use them for 2 line comments sometimes if I feel it's important enough or it's just easier to have more space.

I leave the first and last lines blank:
/*
* comment goes here
* comment goes here
*/

The stars are lined up always, since emacs does that for me.

User avatar
adlaiff6
Posts: 274
Joined: Fri Nov 10, 2006 6:08 am UTC
Location: Wouldn't you rather know how fast I'm going?
Contact:

Re: Comments

Postby adlaiff6 » Sun Dec 02, 2007 9:22 pm UTC

poun-difs ear-oh!
3.14159265... wrote:What about quantization? we DO live in a integer world?

crp wrote:oh, i thought you meant the entire funtion was f(n) = (-1)^n
i's like girls u crazy

DragonWrangler
Posts: 45
Joined: Sun Apr 15, 2007 6:26 pm UTC

Re: Comments

Postby DragonWrangler » Mon Dec 03, 2007 12:38 am UTC

With multi line comments, I like them to line up so I do

Code: Select all

/*some words
**more words
**and a few more
*/

User avatar
JamesCFraser
Posts: 32
Joined: Wed Nov 14, 2007 9:47 pm UTC

Re: Comments

Postby JamesCFraser » Mon Dec 03, 2007 2:00 am UTC

I've never written a program in a team, so have never gotten into commenting.
That said, when I use Pascal I write comments of this form:

Code: Select all

if condition
then
  statement
{end if};

_peterb
Posts: 5
Joined: Fri Nov 16, 2007 1:58 am UTC
Contact:

Re: Comments

Postby _peterb » Tue Dec 04, 2007 12:03 am UTC

Comments are necessary - they should augment code where necessary however most code should self document. Comments are designed to be read by people reading the code - therefore they should not require any form of preprocessing (no image tags) ie Javadoc is bad.

If people want to combine documentation with commenting (which is a good idea), some system that processes natural language ASCII (or unicode) such as markdown should be used.

IMHO

Peter

User avatar
OmenPigeon
Peddler of Gossamer Lies
Posts: 673
Joined: Mon Sep 25, 2006 6:08 am UTC
Contact:

Re: Comments

Postby OmenPigeon » Tue Dec 04, 2007 4:25 am UTC

Shame on all of you. The proper way to comment is, of course,

Code: Select all

""" Oh, man, look at all the awesome things happening in my code.
    You should really read this because it is IMPORTANT. """

The best part is, when you write the comment above a function declaration, you get something like

Code: Select all

""" This is a function.  It does amazing things,
    and you should gaze upon it with wonder and joy,
    for my code is the One True Code, and when you
    finally accept that in your heart, all will be well with
    your immortal soul. """
def foo(bar, baz):
    amazing things are happening here
    just look
    I promise, it's really pretty great

And everything but the 'def' and initial '"""' is indented to the same level, even the name of the function. Le bliss.
As long as I am alive and well I will continue to feel strongly about prose style, to love the surface of the earth, and to take pleasure in scraps of useless information.
~ George Orwell

User avatar
b.i.o
Green is the loneliest number
Posts: 2519
Joined: Fri Jul 27, 2007 4:38 pm UTC
Location: Hong Kong

Re: Comments

Postby b.i.o » Tue Dec 04, 2007 6:38 am UTC

JamesCFraser wrote:I've never written a program in a team, so have never gotten into commenting.
That said, when I use Pascal I write comments of this form:

Code: Select all

if condition
then
  statement
{end if};


I tend to forget exactly what my own code does after a few days if I don't comment it at least a bit...

User avatar
JamesCFraser
Posts: 32
Joined: Wed Nov 14, 2007 9:47 pm UTC

Re: Comments

Postby JamesCFraser » Tue Dec 04, 2007 1:16 pm UTC

Silver2Falcon wrote:
JamesCFraser wrote:I've never written a program in a team, so have never gotten into commenting.
That said, when I use Pascal I write comments of this form:

Code: Select all

if condition
then
  statement
{end if};


I tend to forget exactly what my own code does after a few days if I don't comment it at least a bit...


I prefer not to comment as it gives me experience in seeing how something works just from the code. I can pretty much always see what my own code is doing just reading it.

That said, I do use meaningful variable names

User avatar
enk
Posts: 754
Joined: Mon Sep 10, 2007 12:20 am UTC
Location: Aalborg, Denmark
Contact:

Re: Comments

Postby enk » Tue Dec 04, 2007 3:08 pm UTC

JamesCFraser wrote:I prefer not to comment as it gives me experience in seeing how something works just from the code. I can pretty much always see what my own code is doing just reading it.


That can be really difficult, esp. if it's written by someone else.

Consider this program in Casio Basic. I know what it does and have used it a lot, but I simply can't say how it works. But then again, this language only allows one-char variable names :roll:

Spoiler:

Code: Select all

# TITLE:  Approximate Fraction         
# AUTHOR: Karl Ove Hufthammer
# EMAIL:  huftis@bigfoot.com
# WEB:    ?                   
# DATE:   ?
# MAKE:   CASIO
# MODEL:  9850     
# NOTES: 
#
# Just type in a number, and press EXE until you get a accurate enough
# fraction. It's useful with repeating decimal numbers (like 2,715151515...),
# but you can also get good approximations from other numbers (try pi!).

# The program displays the numerator (stored in U), the denominator
# (stored in V), the resulting number, the original number and the
# difference between these two.


@@ Program "APPFRAC"






"Number"?->N
N->B
1->R
Do
  10N->N
  10R->R
LpWhile Frac N<>0
1->S~Y
0->T~X
Do
  N->M
  R->N
  Int (M/N->Q
  M-QN->R
  QY+T->U
  QX+S->V
  U/V->Z
  Locate 2,1,U
  Locate 2,2,V
  Locate 2,3,"-------------"
  Locate 2,4,Z
  Locate 2,5,B
  Locate 2,6,"-------------"
  Locate 2,7,Abs (B-Z
  Do
  LpWhile Getkey<>31
  Y->T
  U->Y
  X->S
  V->X
  LpWhile R>0
Locate 2,7,"Finished"


phlip wrote:Ha HA! Recycled emacs jokes.

User avatar
b.i.o
Green is the loneliest number
Posts: 2519
Joined: Fri Jul 27, 2007 4:38 pm UTC
Location: Hong Kong

Re: Comments

Postby b.i.o » Tue Dec 04, 2007 3:19 pm UTC

enk wrote:
JamesCFraser wrote:I prefer not to comment as it gives me experience in seeing how something works just from the code. I can pretty much always see what my own code is doing just reading it.


That can be really difficult, esp. if it's written by someone else.

Consider this program in Casio Basic. I know what it does and have used it a lot, but I simply can't say how it works. But then again, this language only allows one-char variable names :roll:

Spoiler:

Code: Select all

# TITLE:  Approximate Fraction         
# AUTHOR: Karl Ove Hufthammer
# EMAIL:  huftis@bigfoot.com
# WEB:    ?                   
# DATE:   ?
# MAKE:   CASIO
# MODEL:  9850     
# NOTES: 
#
# Just type in a number, and press EXE until you get a accurate enough
# fraction. It's useful with repeating decimal numbers (like 2,715151515...),
# but you can also get good approximations from other numbers (try pi!).

# The program displays the numerator (stored in U), the denominator
# (stored in V), the resulting number, the original number and the
# difference between these two.


@@ Program "APPFRAC"






"Number"?->N
N->B
1->R
Do
  10N->N
  10R->R
LpWhile Frac N<>0
1->S~Y
0->T~X
Do
  N->M
  R->N
  Int (M/N->Q
  M-QN->R
  QY+T->U
  QX+S->V
  U/V->Z
  Locate 2,1,U
  Locate 2,2,V
  Locate 2,3,"-------------"
  Locate 2,4,Z
  Locate 2,5,B
  Locate 2,6,"-------------"
  Locate 2,7,Abs (B-Z
  Do
  LpWhile Getkey<>31
  Y->T
  U->Y
  X->S
  V->X
  LpWhile R>0
Locate 2,7,"Finished"




I know what you mean. I simply can't follow anything moderately complicated in TI-Basic. No meaningful variable names, no comments, and only 8 lines on the screen at once.

User avatar
enk
Posts: 754
Joined: Mon Sep 10, 2007 12:20 am UTC
Location: Aalborg, Denmark
Contact:

Re: Comments

Postby enk » Tue Dec 04, 2007 3:29 pm UTC

Silver2Falcon wrote:
enk wrote:
JamesCFraser wrote:I prefer not to comment as it gives me experience in seeing how something works just from the code. I can pretty much always see what my own code is doing just reading it.


That can be really difficult, esp. if it's written by someone else.

Consider this program in Casio Basic. I know what it does and have used it a lot, but I simply can't say how it works. But then again, this language only allows one-char variable names :roll:

Spoiler:

Code: Select all

# TITLE:  Approximate Fraction         
# AUTHOR: Karl Ove Hufthammer
# EMAIL:  huftis@bigfoot.com
# WEB:    ?                   
# DATE:   ?
# MAKE:   CASIO
# MODEL:  9850     
# NOTES: 
#
# Just type in a number, and press EXE until you get a accurate enough
# fraction. It's useful with repeating decimal numbers (like 2,715151515...),
# but you can also get good approximations from other numbers (try pi!).

# The program displays the numerator (stored in U), the denominator
# (stored in V), the resulting number, the original number and the
# difference between these two.


@@ Program "APPFRAC"






"Number"?->N
N->B
1->R
Do
  10N->N
  10R->R
LpWhile Frac N<>0
1->S~Y
0->T~X
Do
  N->M
  R->N
  Int (M/N->Q
  M-QN->R
  QY+T->U
  QX+S->V
  U/V->Z
  Locate 2,1,U
  Locate 2,2,V
  Locate 2,3,"-------------"
  Locate 2,4,Z
  Locate 2,5,B
  Locate 2,6,"-------------"
  Locate 2,7,Abs (B-Z
  Do
  LpWhile Getkey<>31
  Y->T
  U->Y
  X->S
  V->X
  LpWhile R>0
Locate 2,7,"Finished"




I know what you mean. I simply can't follow anything moderately complicated in TI-Basic. No meaningful variable names, no comments, and only 8 lines on the screen at once.


Ow.. that beats my Casio fx-9750G PLUS. Only six lines of code visible, each line 21 chars long. But I learned the basics of coding on that machine. Of course, most of my programs and games started as pseudo code on paper :)

Comments, however, are possible on the Casio. Just write it between double quotes:

Code: Select all

?->A
"MAIN LOOP"
Do
...
...
...
phlip wrote:Ha HA! Recycled emacs jokes.

User avatar
TomBot
Posts: 228
Joined: Sun Jul 29, 2007 1:17 am UTC
Location: Illinois (UIUC)
Contact:

Re: Comments

Postby TomBot » Wed Dec 05, 2007 5:11 am UTC

btilly wrote:
Rysto wrote:Commented-out code of any kind should never make it back into the repository anyway. And any self-respecting IDE recognizes #if 0 and will format the code as a comment anyway.

I've seen plenty of commented out code that made it back to a repository. Why? Because the person who commented it out expects it to be uncommented again sometime. I'll agree that this is often done when it shouldn't be. But sometimes it makes sense.

For instance I might leave in some commented out debugging statements in languages without preprocessors. Some day I'll want to see what queries are hitting the database. Right now I don't.


If you do that, then when you do want to see the debugging output again, you'll have to turn it on everywhere. A much better idea would be to make a debug function, which you can then simply disable in one place.

In my experience, people who comment out code never explain why. Sometimes it's pretty obvious, like they commented out destructors because they crash. Ugh. I won't say it's a cause, but commented out code is strongly correlated with crappy code.

If you feel the need to put an #if 0, consider #if SOME_DESCRIPTIVE_THING, possibly with a comment, in case you do end up committing it.

btilly
Posts: 1877
Joined: Tue Nov 06, 2007 7:08 pm UTC

Re: Comments

Postby btilly » Wed Dec 05, 2007 5:46 am UTC

TomBot wrote:
btilly wrote:
Rysto wrote:Commented-out code of any kind should never make it back into the repository anyway. And any self-respecting IDE recognizes #if 0 and will format the code as a comment anyway.

I've seen plenty of commented out code that made it back to a repository. Why? Because the person who commented it out expects it to be uncommented again sometime. I'll agree that this is often done when it shouldn't be. But sometimes it makes sense.

For instance I might leave in some commented out debugging statements in languages without preprocessors. Some day I'll want to see what queries are hitting the database. Right now I don't.

If you do that, then when you do want to see the debugging output again, you'll have to turn it on everywhere. A much better idea would be to make a debug function, which you can then simply disable in one place.

point.missed();

The point is that occasionally there are some key pieces of information that are useful in debugging lots of different kinds of problems. There are many reasons why I'll want to debug that and only that. I don't want to see a ton of debugging. I just want to see this key piece of information.

The alternative is to use a logger (like Log4J) and just turn logging on/off for a specific logging class. If you're already using a logger, there are lots of reasons to do exactly that. If you're working with existing code, it may be easier to comment out one block rather than try to retrofit a logger on. (Besides, logging imposes overhead. The logging itself is generally lightweight, but runtime stringification of data on the way to calling the logging function can get expensive. Been there, done that.)
TomBot wrote:In my experience, people who comment out code never explain why. Sometimes it's pretty obvious, like they commented out destructors because they crash. Ugh. I won't say it's a cause, but commented out code is strongly correlated with crappy code.

If you feel the need to put an #if 0, consider #if SOME_DESCRIPTIVE_THING, possibly with a comment, in case you do end up committing it.

I'll happily agree that commented out code is a red flag. But red flags are signs of potential problems, not necessarily real ones. And sometimes small amounts of commented out code is OK.
Some of us exist to find out what can and can't be done.

Others exist to hold the beer.


Return to “Religious Wars”

Who is online

Users browsing this forum: No registered users and 2 guests