Style comments for beginner 
Author Message
 Style comments for beginner

I am teaching myself C through books and using lcc. I miss having a
classroom and a teacher to ask questions. Through my lurking, I've seen
posts from students who are advanced beyond me, but I haven't found a
newsgroup for newbies or rank beginners.

So, here's my first attempt at a student program. I'd appreciate any
tips or comments. It runs in lcc though I haven't tested it in a unix
environment.

Cheers!
Michael

/*PointerPassing demonstrates passing parameters to and from
  functions by use of pointers*/
#include <stdio.h>
 /*Prototype for prtyrs1() and prtyrs2*/
 /*prtyrs1() passes integer variables and
   prtyrs2() passes pointers to integer variables*/
int prtyrs1(int, int, int); int prtyrs2(int *, int *, int *);

int main()
{
 /*Initialize the three years*/
int year1=1956, year2=1959, year3=1977;
 /*Show the original years*/
printf("Years 0 : %6d%6d%6d\n\n",year1,year2,year3);
 /*Call the function with variables and return*/
prtyrs1(year1, year2, year3);
 /*Prove they weren't returned (changed)*/
printf("Years 0 : %6d%6d%6d\n\n",year1,year2,year3);
 /*Call the function with pointers and return*/
prtyrs2(&year1, &year2, &year3);
 /*Prove they were changed*/
printf("Years 0 : %6d%6d%6d\n",year1,year2,year3);
return 0;

Quote:
}

/*End of PointerPassing*/
/*=====================*/

int prtyrs1(int year1, int year2, int year3)
 {
 printf("Years 1 : %6d%6d%6d\n",year1,year2,year3);
  /*Increment the years & print*/
 year1++;year2++;year3++;
 printf("Years 1a: %6d%6d%6d\n\n",year1,year2,year3);
  /*The higher years will not be returned*/
 return 0;
 }
/*End of prtyrs1*/

int prtyrs2(int *tmpyr1, int *tmpyr2, int *tmpyr3)
 {
 printf("Years 2 : %6d%6d%6d\n",*tmpyr1,*tmpyr2,*tmpyr3);
  /*Increment the years & print*/
 *tmpyr1=*tmpyr1+1; *tmpyr2=*tmpyr2+1; *tmpyr3=*tmpyr3+1;
 printf("Years 2a: %6d%6d%6d\n\n",*tmpyr1,*tmpyr2,*tmpyr3);
  /*The higher years will be returned from here*/
 return 0;
 }
/*End of prtyrs2*/
--



Fri, 09 Nov 2001 03:00:00 GMT  
 Style comments for beginner
I'll mention three things.

While it's no big deal in a toy program like this, when you're writing
something larger it's often a good idea to avoid variable names that
differ only at the end, like tmpyr1 and tmpyr2.  They're just a little
harder to read.

Quote:
>  *tmpyr1=*tmpyr1+1; *tmpyr2=*tmpyr2+1; *tmpyr3=*tmpyr3+1;

++ could be used here, just as in the other function.  Because it's
*tmpyr1 and not tmpyr1 that you want to increment, you need parentheses:

   (*tmpyr1)++;

Alternatively, since you don't care IN THIS CONTEXT about the difference
between prefix and postfix ++, you could also write

   ++*tmpyr1;

which needs no parentheses since the position of ++ before * clarifies
what's meant.  I think most C programmers would write it this way.

Quote:
>  printf("Years 2a: %6d%6d%6d\n\n",*tmpyr1,*tmpyr2,*tmpyr3);

Suppose you had messed something up and the numbers being printed were
actually -1912041415, 18890612, and 193945 instead of what you expected.
Then your output would look like:

  Years 2a: -191204141518890612193945

This might (or, of course, might not) be a little easier to debug
if instead the three numbers were visible:

  Years 2a: -1912041415 18890612 193945

So I suggest using "%6d %5d %5d" rather than "%6d%6d%6d" in the format.
In general, always put some space between different items to be written
out unless you actually want them to be run together; don't rely on the
minimum field width to do the spacing for you.

(Perhaps your machine has 16-bit ints and you figured %6d would be wide
enough for any possible int.  But you can't count on integer types having
particular sizes in C; the standard guarantees only a minimum size.  In
fact, 32-bit ints are very common.)
--
Mark Brader             |  "I already checked, and there are 2147483647
Toronto                 |   natural numbers (I made a simple Java program

My text in this article is in the public domain.
--



Sat, 10 Nov 2001 03:00:00 GMT  
 Style comments for beginner

   I am teaching myself C through books and using lcc. I miss having a
   classroom and a teacher to ask questions. Through my lurking, I've seen
   posts from students who are advanced beyond me, but I haven't found a
   newsgroup for newbies or rank beginners.

   So, here's my first attempt at a student program. I'd appreciate any
   tips or comments. It runs in lcc though I haven't tested it in a unix
   environment.

   Cheers!
   Michael

   /*PointerPassing demonstrates passing parameters to and from
     functions by use of pointers*/

Use more spaces to make it more readable.  Also, put periods at the
end of your sentences:

   /* PointerPassing demonstrates passing parameters to and from
      functions by use of pointers. */

   #include <stdio.h>
    /*Prototype for prtyrs1() and prtyrs2*/
    /*prtyrs1() passes integer variables and
      prtyrs2() passes pointers to integer variables*/
   int prtyrs1(int, int, int); int prtyrs2(int *, int *, int *);

Make that two lines:
   int prtyrs1 (int, int, int);
   int prtyrs2 (int *, int *, int *);

   int main()
   {
    /*Initialize the three years*/
   int year1=1956, year2=1959, year3=1977;

Always indent comments and the statements that they go with to the
same level.  Don't make worthless comments.  Most of your comments in
this program are useless; i.e., the one above doesn't tell the reader
anything that isn't obvious from the code itself.

Please indent statements in functions away from the left margin by at
least two spaces.  This helps to visually distinguish statements from
file-level declarations.

    /*Show the original years*/
   printf("Years 0 : %6d%6d%6d\n\n",year1,year2,year3);
    /*Call the function with variables and return*/
   prtyrs1(year1, year2, year3);
    /*Prove they weren't returned (changed)*/
   printf("Years 0 : %6d%6d%6d\n\n",year1,year2,year3);
    /*Call the function with pointers and return*/
   prtyrs2(&year1, &year2, &year3);
    /*Prove they were changed*/
   printf("Years 0 : %6d%6d%6d\n",year1,year2,year3);
   return 0;
   }
   /*End of PointerPassing*/
   /*=====================*/

Immediately above is a comment that's confusing.  You haven't declared
anything named PointerPassing, but you comment on it.

   int prtyrs1(int year1, int year2, int year3)
    {
    printf("Years 1 : %6d%6d%6d\n",year1,year2,year3);

Please put a space after each comma for readability.  I use GNU style
and put a space before each left parenthesis as well, but this isn't
common style:

    printf ("Years 1 : %6d%6d%6d\n", year1, year2, year3);

     /*Increment the years & print*/
    year1++;year2++;year3++;

Three separate lines please, or at the least separate the statements
by spaces.

    printf("Years 1a: %6d%6d%6d\n\n",year1,year2,year3);
     /*The higher years will not be returned*/
    return 0;
    }
   /*End of prtyrs1*/

Another silly comment.  It should be obvious.

   int prtyrs2(int *tmpyr1, int *tmpyr2, int *tmpyr3)
    {
    printf("Years 2 : %6d%6d%6d\n",*tmpyr1,*tmpyr2,*tmpyr3);
     /*Increment the years & print*/
    *tmpyr1=*tmpyr1+1; *tmpyr2=*tmpyr2+1; *tmpyr3=*tmpyr3+1;
    printf("Years 2a: %6d%6d%6d\n\n",*tmpyr1,*tmpyr2,*tmpyr3);
     /*The higher years will be returned from here*/
    return 0;
    }
   /*End of prtyrs2*/

Well, you asked for style comments, and I hope these help.
--



Sat, 10 Nov 2001 03:00:00 GMT  
 Style comments for beginner

Quote:

> I am teaching myself C through books and using lcc. I miss having a
> classroom and a teacher to ask questions. Through my lurking, I've seen
> posts from students who are advanced beyond me, but I haven't found a
> newsgroup for newbies or rank beginners.

The group you're looking for is:

alt.comp.lang.learn.c-c++

Regards
Friedrich
--



Sat, 10 Nov 2001 03:00:00 GMT  
 Style comments for beginner

Quote:
> So, here's my first attempt at a student program. I'd appreciate any
> tips or comments. It runs in lcc though I haven't tested it in a unix
> environment.

[This is pretty long, but it's an open-ended question that
I think is a good one to see discussed every once in a while.  My
take at editing the code is at the end.  Obviously style is
very personal; I've limited myself to describing style features and
commenting styles that are fairly well-accepted and avoided OTBS
flamewars]

It's mostly straight C that should run anywhere, though for
really strict ANSI compliance you have to make sure that the
identifiers are unique in the first 5 characters.  That is,
prtyrs1 and prtyrs2 would have to be yrs1 and yrs2 and so
forth.  I personally wouldn't worry about this; I think that
the gain from having somewhat descriptive identifiers is worth
the loss of portability to certain old and draconian compilers.

One thing that's clearly off in your program is the use of comments.
You have way too many of them.  You probably read somewhere that
commenting the code is good; that's true, but only inasmuch as it
makes the code more readable.  Overcommenting is distracting and
makes it harder to find the really useful comments.  

As a beginner, it's sometimes difficult to know what the useful
comments are.  A decent rule of thumb is to avoid commenting C
language behaviour and C library behavior.  Comment the general
methods that you're using in a function and comment anything
unusual or unclear that you're doing.  Let the language take care
of the rest.  A comment at the top of every file and at the top
of every function is a good idea; explain what the function takes
for parameters and what it returns.  Also say which parameters it
can modify and what possible errors are.  The comment at the top of
the file should give an overview and possibly some references.  You
might see something like:

/*
 * rbtree.c   Copyright 1999 Gerry Sumner Hayes.  All rights reserved.
 * This may be distributed under the DPL -- see DIATRIBE for specifics.
 *
 * This file implements red-black trees, as describe in
 * Knute Donaldson's book "Plant a Tree!" (SpazmoPress, 1917).  To
 * use, #include <rbtree.h>.  Read the comments there and the README
 * file for more info.
 *
 * This is a threaded red-black tree, so inorder traversal is rockin'.
 *
 * For instructions on how to compile, see the INSTALL file.
 */

I wouldn't comment too many lines within the code unless they aren't
clear from context.  Something like:

int babbleX(int a, int b)
{
    int rv;

    if(a==0) return 0;
    if(b==0) return -1;

    rv=(a^b)|b;  /* Russonovich's forward tumble algorithm */

    if(rv<100) return -1;
    return rv;

Quote:
}

is typical -- notice that the only inline comment is to document
how something is being done and doesn't tell what the C is but
rather what the concept is.

Another kind of inline comment that's (unfortunately) common is:

/* XXX: This code doesn't work if the snurgle is blue.  To fix that,
 * we'd need to know if the swallow is African or European, but we
 * can't get that information from the gatekeeper.  */

That sort of comment specifies a problem with the code.  It also gives
a hint at how to fix it and tells why that isn't done yet.  It's
customary to start those comments with XXX or FIXME; that way, people
can easily use the search function of their editor to find them.

Another kind of comment that is useful is one that tells why something
isn't done in the obvious way.

/* We have to do it this way because on some platforms the fd may
 * not be an int */

or

/* This is to work around a bug in Yodelsoft C Compiler v2.1 */

or

/* We used to use getnuzzleinfo() to find this out, but that doesn't
 * work if creature.type is negative so we need to get it from the
 * user */

Here's an example of how I would write your code.  I declare the
functions as "static void" -- "static" since they're not called from
outside this file and "void" since they don't have a meaningful return
value. If you declare them int, they should do something like return 0
or a positive value to indicate the number of years incremented and -1
to indicate an error.  If you did that, you'd want to add a "Returns"
section to the comments on the functions.  I explicitly declare main
as taking no arguments ("int main(void)").  The descriptions I put in
the comments under "Parameters" are obviously incorrect, but they are
there to illustrate what _kind_ of comments I would use.  Notice how
I've tried to use whitespace to group similar thoughts together.

/*
 * PointerPassing demonstrates passing parameters to and from
 * functions by use of pointers
 */

#include <stdio.h>

static void prtyrs1(int, int, int);
static void prtyrs2(int *, int *, int *);

/*
 * This demonstrates that C uses pass by value rather than pass by
 * reference.  The call to prtyrs1 is by value; the call to prtyrs2
 * passes the addresses of the years so they can be modified.
 */
int main(void)
{
    int year1=1956, year2=1959, year3=1977;

    printf("Years 0 : %6d%6d%6d\n\n",year1,year2,year3);

    prtyrs1(year1, year2, year3);
    printf("Years 0 : %6d%6d%6d\n\n",year1,year2,year3);

    prtyrs2(&year1, &year2, &year3);
    printf("Years 0 : %6d%6d%6d\n",year1,year2,year3);

    return 0;

Quote:
}

/*
 * ptryrs1
 * Parameters: year1 is the year my mom was born.  year2 is the
 *             year dad was born.  year3 is the year I was born.
 * Side effects: Prints the years and prints incremented versions of
 *               the years
 */
static void prtyrs1(int year1, int year2, int year3)
{
    printf("Years 1 : %6d%6d%6d\n", year1, year2, year3);

    year1++;
    year2++;
    year3++;

    printf("Years 1a: %6d%6d%6d\n\n", year1, year2, year3);

    return 0;

Quote:
}

/*
 * ptryrs2
 * Parameters: tmpyr1 is the address of the current year, tmpyr2
 *             is the address of my birthyear, tmpyr3 is the address
 *             of the year that the next election is held
 * Side effects: Prints the years.  Increments them to new values.
 *             Prints them again.
 */
static void prtyrs2(int *tmpyr1, int *tmpyr2, int *tmpyr3)
{
    printf("Years 2 : %6d%6d%6d\n", *tmpyr1, *tmpyr2, *tmpyr3);

    *tmpyr1 += 1;
    *tmpyr2 += 1;
    *tmpyr3 += 1;

    printf("Years 2a: %6d%6d%6d\n\n", *tmpyr1, *tmpyr2, *tmpyr3);

    return 0;

Quote:
}

--



Sat, 10 Nov 2001 03:00:00 GMT  
 Style comments for beginner

Quote:
> int prtyrs1(int, int, int); int prtyrs2(int *, int *, int *);

I'd write each prototype on a separate line, and perhaps add names of
parameters.

The function names look somewhat cryptic, in particular the numerical
suffixes which don't really mean anything (in the sense of BSD Unix
wait3() vs. wait4()).  This may be okay in such a small program, but
in a larger one the names should be clearer, especially when the
functions aren't static.

Quote:
> int main()

Here I'd make the parameter list explicitly void.

Quote:
> printf("Years 0 : %6d%6d%6d\n\n",year1,year2,year3);

It may be better to print the numbers with "%5d %5d %5d"; that way
there's no chance of their getting stuck in each other even if they
are larger than you thought.

Quote:
> int prtyrs1(int year1, int year2, int year3)
>  {
...
>  return 0;
>  }

Since prtyrs1() and prtyrs2() always return 0 and main() does not use
the values returned, I'd change the return types to void and omit the
return statements.

Quote:
>  *tmpyr1=*tmpyr1+1; *tmpyr2=*tmpyr2+1; *tmpyr3=*tmpyr3+1;

This can also be written as
*tmpyr1 += 1; *tmpyr2 += 1; *tmpyr3 += 1;  /* IMHO the clearest way */
or
(*tmpyr1)++; (*tmpyr2)++; (*tmpyr3)++;  /* Parentheses required! */
or
++*tmpyr1; ++*tmpyr2; ++*tmpyr3;
--



Sat, 10 Nov 2001 03:00:00 GMT  
 Style comments for beginner
Gerry Sumner Hayes did a bang-up job clearing up my confusion.

I just have one question.

Quote:
> static void prtyrs1(int year1, int year2, int year3)
> {
>     printf("Years 1 : %6d%6d%6d\n", year1, year2, year3);

>     year1++;
>     year2++;
>     year3++;

>     printf("Years 1a: %6d%6d%6d\n\n", year1, year2, year3);

>     return 0;
> }

I take it that it's better to use void because it will compile faster?
OK, but if I do that, don't I have to eliminate the "return 0"? I get
a compile error otherwise.

Thanks for the excellent replies from everyone.

Cheers!
Michael

--
RASBERRY AGENCY LTD                          Toll-free (800) 532-6715
P O Box 11773, C{*filter*}te, NC 28220-1773          Local (704) 372-2182
300 E Kingston Ave, C{*filter*}te, NC 28203-4746       Fax (704) 335-0535
http://www.*-*-*.com/ ~rasberryagency
--



Mon, 12 Nov 2001 03:00:00 GMT  
 Style comments for beginner



Quote:
> Gerry Sumner Hayes did a bang-up job clearing up my confusion.

> I just have one question.

> > static void prtyrs1(int year1, int year2, int year3)
> > {
> >     printf("Years 1 : %6d%6d%6d\n", year1, year2, year3);

> >     year1++;
> >     year2++;
> >     year3++;

> >     printf("Years 1a: %6d%6d%6d\n\n", year1, year2, year3);

> >     return 0;
> > }

> I take it that it's better to use void because it will compile faster?
> OK, but if I do that, don't I have to eliminate the "return 0"? I get
> a compile error otherwise.

It'll save you a MOV EAX, Value instruction per function call, which could make
your code run a tiny bit faster.  You're very unlikely to notice the effect
unless you have a real-time program running on an ancient system, however.  As
for the return value, you can just either type "return;" with no value or let
the function come to the ending brace; either one would work.    If you want
more information, alt.comp.lang.learn.c-c++ is probably a better place for you
to ask.  Most of the posts in this newsgroup involve the LCC compiler rather
than the language itself.

-Harold Weissfield

--



Fri, 23 Nov 2001 03:00:00 GMT  
 Style comments for beginner
[This followup was also e-mailed to the cited author for speed -- please
follow up in the newsgroup.]


comp.lang.c.moderated:

Quote:
>Gerry Sumner Hayes did a bang-up job clearing up my confusion.
>> static void prtyrs1(int year1, int year2, int year3)
>> {
>>     return 0;
>> }

>I take it that it's better to use void because it will compile faster?

No, compile speed is not an issue. Use "void" when the function does
something but will not return a value; use a type when the function will
return a value.

Quote:
>OK, but if I do that, don't I have to eliminate the "return 0"? I get
>a compile error otherwise.

Right -- I think the previous person made a thinko. In a void-type
function, return statements must not have values. You could put a plain
        return;
at the end, or omit it and let the compiler infer it for you.

--
There's no need to e-mail me a copy of a follow-up; but if you do,
please identify it as such.

Stan Brown, Oak Road Systems, Cleveland, Ohio, USA
                                    http://www.mindspring.com/~brahms/
My reply address is correct as is. The courtesy of providing a correct
reply address is more important to me than time spent deleting spam.
--



Fri, 23 Nov 2001 03:00:00 GMT  
 Style comments for beginner

Quote:

> Gerry Sumner Hayes did a bang-up job clearing up my confusion.

> I just have one question.

> > static void prtyrs1(int year1, int year2, int year3)
> > {
[SNIP]
> >     return 0;
> > }

> I take it that it's better to use void because it will compile faster?

No, use void to indicate that the return value doesn't matter.  

Quote:
> OK, but if I do that, don't I have to eliminate the "return 0"? I get
> a compile error otherwise.

Yes.  My error.  Use "return;" (without a value) or eliminate the
return statement entirely.  I prefer to use return, but that's a
matter of personal preference.  Just be consistent.

--Sumner
--



Fri, 23 Nov 2001 03:00:00 GMT  
 Style comments for beginner

Quote:

> for really strict ANSI compliance you have to make sure that the
> identifiers are unique in the first 5 characters.  That is,
> prtyrs1 and prtyrs2 would have to be yrs1 and yrs2 and so
> forth.

[snip]

I thought it was the first 6 characters. "... for internal
identifiers, at least the first 31 characters are significant ...
Identifiers with external linkage are more restricted:
implementations may make as few as the first six characters
significant, and may ignore case distinctions" (K&R2,
Section A2.3).
--



Fri, 23 Nov 2001 03:00:00 GMT  
 
 [ 11 post ] 

 Relevant Pages 

1. Commenting style (was: Call for folklore)

2. javadoc style commenting for C code

3. Commenting Styles

4. Request for comment; Re: Coding style

5. DoDont series I: comment style I

6. DoDont series 1: comment style I

7. Commenting style

8. Comments wanted: iostream code style

9. A new C comment style

10. ANSI C style comments

11. Commenting style (was: Call for folklore)

12. Lisp-style comments

 

 
Powered by phpBB® Forum Software