DoDont series 1: comment style I 
Author Message
 DoDont series 1: comment style I

DoDont Series-1

Any comments, including {*filter*} threat, will be welcome.  So feel free to

make a comment regarding my following statements.

[1].  Comment Style

1. Don't use // comment style in a C program. Because // comment style
is
not accepted as a standard and because, when you used the // comment
style
and when you tried to print your source code using a black and white
laser printer, by the appearance of the '//' characters, you will have
a little hard time to get a notion that the trailing char's following
the '//' are the comments.  If you use '/*' and '*/' sets instead,
easily
you can get a notion that the char's between '/*' and '*/' are the
comments.

For example, if you have printed following code using black/white laser
printer, I mean, you should spend a little time to discriminate comment
parts from non-comments parts due to the intrinsic appearance of the
'//' chars.

=====
//
// The strchr() function returns a pointer to the first occurrence
// of the character c in the string s.
//

char *
strchr(const char * s, int c)
{
        for(; *s != (char) c; ++s) // this is a comment
                if (*s == '\0') // this is another comment
                        return NULL;
        return (char *) s;

Quote:
}

=====
/*
 * The strchr() function returns a pointer to the first occurrence
 * of the character c in the string s.
 */
char *
strchr(const char * s, int c)
{
        for(; *s != (char) c; ++s) /* this is a comment */
                if (*s == '\0') /* this is another comment */
                        return NULL;
        return (char *) s;
Quote:
}

====

2. Dont make useless, futile, or strange looking, block comments.

I recommend the following comment style as a template.

[DO]
/*
 * The strchr() function returns a pointer to the first occurrence of
the
 * character c in the string s.
 */

However, don't use tab char's in the block comment whenever possible. I
mean
you should not insert tab char before the 'The strchr() function' part
of
the following block comment like following.

[DONT]
/*
 *      The strchr() function returns a pointer to the first occurrence
of
 *      the character c in the string s.
 */

Also, Do make the block comment utilize the full line, usually
80-column.
By fully utilizing the 80 column, we can also use this block comment as
a
separator which discriminates one function from another function.
Therefore,
I mean, dont make following block comment.

[DONT]
/*
 * The strchr() function returns a pointer to
 * the first occurrence of the character c in
 * the string s.
 */

I met following block comments many years ago.  I hate these styles.
So I DO NOT recommend following comment styles.

[DONT]
/*
** The strchr() function returns a pointer to the first occurrence of
the
** character c in the string s.
**/

[DONT]
/* */
/* The strchr() function returns a pointer to the first occurrence of
the */
/* character c in the string s. */
/* */

[DONT]
/*
 The strchr() function returns a pointer to the first occurrence of the
 character c in the string s.
 */

[DONT]
/* The strchr() function returns a pointer to the first occurrence of
the */
/* character c in the string
s.                                           */

[DONT]
/* The strchr() function returns a pointer to the first occurrence of
the */
/* character c in the string s. */

[DONT]
/*
; The strchr() function returns a pointer to the first occurrence of the

; character c in the string s.
*/

[DONT]
/**************************************************************************/

/* The strchr() function returns a pointer to the first occurrence of
the */
/* character c in the string
s.                                           */
/**************************************************************************/

[DONT]
/**************************************************************************\

 * The strchr() function returns a pointer to the first occurrence of
the *
 * character c in the string
s.                                           *
\**************************************************************************/

[DONT]
/**************************************************************************

 The strchr() function returns a pointer to the first occurrence of the
 character c in the string s.
***************************************************************************/

[DONT]
/*=========================================================================

 The strchr() function returns a pointer to the first occurrence of the
 character c in the string s.
 =========================================================================*/

Let me give me a chance to talk about the 1-line comment.

I recommend following one.
[DO]
/* The strchr() returns a pointer to the first occurrence of c */

However whenever possible, dont insert tab char in above line.

[DONT]
/*      The strchr() returns a pointer to the first occurrence of c */

Please make '*/' char's follow the comment line immediately. I mean,
dont
make following line.

[DONT]
/* The strchr() returns a pointer to the first occurrence of
c              */



Sun, 30 Sep 2001 03:00:00 GMT  
 DoDont series 1: comment style I


Quote:
>DoDont Series-1

>Any comments, including {*filter*} threat, will be welcome.  So feel free to

>make a comment regarding my following statements.

>[1].  Comment Style

>1. Don't use // comment style in a C program. Because // comment style
>is
>not accepted as a standard and because, when you used the // comment
>style

There's one simple overriding reason not to use // comments in C: C doesn't
support // comments, a conforming C compiler must complain about there use.
To put it another way if you use // comments you aren't writing in C.

I'd be interested to see what the reaction of the C++ community would be
if you applied your comments to that language however. :-)

--
-----------------------------------------


-----------------------------------------



Sun, 30 Sep 2001 03:00:00 GMT  
 DoDont series 1: comment style I

Quote:

>Any comments, including {*filter*} threat, will be welcome.  So feel free to
>make a comment regarding my following statements.

>[1].  Comment Style

>1. Don't use // comment style in a C program. Because // comment style is
>not accepted as a standard and because, when you used the // comment style
>and when you tried to print your source code using a black and white
>laser printer, by the appearance of the '//' characters, you will have
>a little hard time to get a notion that the trailing char's following
>the '//' are the comments.  If you use '/*' and '*/' sets instead, easily
>you can get a notion that the char's between '/*' and '*/' are the
>comments.

If you expect your code to have a possibility of being compiled by
a K&R-1 or C89 compiler, then don't use // comments, as such do not
exist in either of those language specifiations.  If you are using
a C++ or a proleptic C9x compiler, or expect to only ever compile
using some specific C compiler which supports // comments, then
use which ever form enhances the readability of the code, including
the comments.

Quote:
>For example, if you have printed following code using black/white laser
>printer, I mean, you should spend a little time to discriminate comment
>parts from non-comments parts due to the intrinsic appearance of the
>'//' chars.

[samples of code, with // and /**/ as the only difference, omitted]

Except for the dearth of whitspace between the code and the
in-line comments (which is a failing of both examples), I
do not find either one more intrinsically more readable than
the other.  The // comments stand out just fine to my eye.

Quote:
>2. Dont make useless, futile, or strange looking, block comments.

[Examples omitted]

Except for the word "block" being extraneous, I agree with that
statement.  Add to it: "Do write comments which enhance the understanding
of what the code is supposed to accomplish, in a clear an readable
manner."

While I did find some of the sample block-comment styles to be
excessively cutesy, few of them were particularly offputting.
The main issue seems to be what should a border look like,
and I feel that a border is not required to set off a block
comment, but as long as it is fairly rectangular then it is
easy to ignore and so does not detract from the flow of reading
the comment and/or code.

In short, while I have no problem with your recommended commenting
style, I do think that you are being excessivly picky in "dictating"
to others what the "correct" layout of a comment should be.

                --Ken Pizzini



Sun, 30 Sep 2001 03:00:00 GMT  
 DoDont series 1: comment style I

Quote:
> you can get a notion that the char's between '/*' and '*/' are the

Don't use apostrophe's in plural's.

Gergo

Quote:
> [DONT]

I would write [DON'T] instead, but it's a matter of taste, I guess.

Gergo

--
"As part of the conversion, computer specialists rewrote 1,500
programs; a process that traditionally requires some debugging."
                -- USA Today, referring to the IRS switchover to a new
                   computer system.

GU d- s:+ a--- C++>$ UL+++ P>++ L+++ E>++ W+ N++ o? K- w--- !O !M !V
PS+ PE+ Y+ PGP+ t* 5+ X- R>+ tv++ b+>+++ DI+ D+ G>++ e* h! !r !y+



Sun, 30 Sep 2001 03:00:00 GMT  
 DoDont series 1: comment style I

<snip>

Quote:
>I'd be interested to see what the reaction of the C++ community would be
>if you applied your comments to that language however. :-)

A friend of mine was (may still be!) on the Oracle Data Query development
team. He told me that, although he develops in C++, he never ever uses the
BCPL-style comments. Why? Because he spent N hours (large N) trying to work
out why, in the following code, VeryImportantFunction() wasn't being called:

SomeCallOrOther(); // comment made reference to c:\adir\anotherdir\
VeryImportantFunction();

I see his point. :-)



Sun, 30 Sep 2001 03:00:00 GMT  
 DoDont series 1: comment style I
On Wed, 14 Apr 1999 22:54:38 +0100,

Quote:

>A friend of mine was (may still be!) on the Oracle Data Query development
>team. He told me that, although he develops in C++, he never ever uses the
>BCPL-style comments. Why? Because he spent N hours (large N) trying to work
>out why, in the following code, VeryImportantFunction() wasn't being called:

>SomeCallOrOther(); // comment made reference to c:\adir\anotherdir\
>VeryImportantFunction();

>I see his point. :-)

Groooan... If line-splicing happens before // comment processing
then this is indeed a very bad thing.  (And, alas, it does seem
to be true.)  Okay, I take back anything I may have ever said
in defense of //-style comments.  I am an avid hater of comments
which are magically continued on the next line just because a
comment line happens to end with a \ character, for just the sort
of reason that your ODQ friend encountered.

                --Ken Pizzini



Sun, 30 Sep 2001 03:00:00 GMT  
 DoDont series 1: comment style I
On 14 Apr 1999 22:24:06 GMT, Ken Pizzini vouchsafed:

Quote:
>On Wed, 14 Apr 1999 22:54:38 +0100,

>>A friend of mine was (may still be!) on the Oracle Data Query development
>>team. He told me that, although he develops in C++, he never ever uses the
>>BCPL-style comments. Why? Because he spent N hours (large N) trying to work
>>out why, in the following code, VeryImportantFunction() wasn't being called:

>>SomeCallOrOther(); // comment made reference to c:\adir\anotherdir\
>>VeryImportantFunction();

>>I see his point. :-)

>Groooan... If line-splicing happens before // comment processing
>then this is indeed a very bad thing.  (And, alas, it does seem
>to be true.)  Okay, I take back anything I may have ever said
>in defense of //-style comments.  I am an avid hater of comments
>which are magically continued on the next line just because a
>comment line happens to end with a \ character, for just the sort
>of reason that your ODQ friend encountered.

Of course, the flip side of this is that (lack of) whitespace can get
you into trouble with the other type of comments.  I ran across this one
in the code of a guy who hated spaces:

int example(int *foo)
{
        int bar, baz;

        .
        . Here some usefule value got assigned to bar...
        .

        baz=bar/*foo;

        .
        .
        .

Quote:
}

--
Carl Jacobs - Software Engineer by title, SysAdmin by fait accompli,
ASR's Chief Bastard of Odd Religious Lore by acclamation.
Opinions expressed are not those of Raytheon Systems Company.
cjacobs at fallschurch.esys.com, darian at rtfm.netset.com (munged)


Sun, 30 Sep 2001 03:00:00 GMT  
 DoDont series 1: comment style I
[...]
: Of course, the flip side of this is that (lack of) whitespace can get
: you into trouble with the other type of comments.  I ran across this one
: in the code of a guy who hated spaces:

: int example(int *foo)
: {
:       int bar, baz;
:       .
:       . Here some usefule value got assigned to bar...
:       .
:       baz=bar/*foo;
:       .
: }

You can also have too much whitespace; I once got thoroughly fooled
by a comment terminated with '* /', where the space fell on the 80th
column of the screen.  It was in the middle of a switch statement,
and I couldn't work out why cases n to m, until the next '*/' closed
the comment, were skipped.  It's the only use I've ever found for a
colorising editor.

Will



Sun, 30 Sep 2001 03:00:00 GMT  
 DoDont series 1: comment style I
Hmmm....escaping the newline...oops! Now why couldn't DOS use
the "correct" file path separator...
Quote:


> <snip>

> >I'd be interested to see what the reaction of the C++ community would be
> >if you applied your comments to that language however. :-)

> A friend of mine was (may still be!) on the Oracle Data Query development
> team. He told me that, although he develops in C++, he never ever uses the
> BCPL-style comments. Why? Because he spent N hours (large N) trying to work
> out why, in the following code, VeryImportantFunction() wasn't being called:

> SomeCallOrOther(); // comment made reference to c:\adir\anotherdir\
> VeryImportantFunction();

> I see his point. :-)



Mon, 01 Oct 2001 03:00:00 GMT  
 DoDont series 1: comment style I

Quote:

>Hmmm....escaping the newline...oops! Now why couldn't DOS use
>the "correct" file path separator...

Actually it can. Any C function (standard or non-standard) that requires a
pathname can use either \ or /.  I always use the forward slash..


Tue, 02 Oct 2001 03:00:00 GMT  
 DoDont series 1: comment style I

Quote:


> >Hmmm....escaping the newline...oops! Now why couldn't DOS use
> >the "correct" file path separator...

> Actually it can. Any C function (standard or non-standard) that requires a
> pathname can use either \ or /.  I always use the forward slash..

And you use two 'classes' of pathnames? Your own using '/' and
the ones you get from user input or from the OS containing '\' ?
And convert back and forth? Using tolerant Path-separation functions?
Remember, if you pass your names to the OS ("copy p.txt test/p.txt")
it will answer something like 'illegal option'.

--

Graz, Austria   www.hls-software.com



Wed, 03 Oct 2001 03:00:00 GMT  
 DoDont series 1: comment style I

Quote:



>> >Hmmm....escaping the newline...oops! Now why couldn't DOS use
>> >the "correct" file path separator...

>> Actually it can. Any C function (standard or non-standard) that requires
a
>> pathname can use either \ or /.  I always use the forward slash..

>And you use two 'classes' of pathnames? Your own using '/' and
>the ones you get from user input or from the OS containing '\' ?
>And convert back and forth? Using tolerant Path-separation functions?
>Remember, if you pass your names to the OS ("copy p.txt test/p.txt")
>it will answer something like 'illegal option'.

I usually avoid using the system command for DOS functions preferring to use
my own library of functions for copy/move, etc.  THe system command doesn't
allow a robust way of checking for errors.  As far as path seperation
functions, the compiler I use has functions that handle that already
(fnsplit, splitpath).  If I'm forced to use the system command with user
entered pathname, I'll put the path through a flipslash() function I wrote
before adding any parameters

- Show quoted text -

Quote:
>--

>Graz, Austria   www.hls-software.com



Wed, 03 Oct 2001 03:00:00 GMT  
 
 [ 12 post ] 

 Relevant Pages 

1. DoDont series I: comment style I

2. DoDont Series 2 : #include, #define

3. DoDont Series 4 - semicolons

4. DoDont Series 3 : struct

5. Commenting style (was: Call for folklore)

6. javadoc style commenting for C code

7. Style comments for beginner

8. Commenting Styles

9. Request for comment; Re: Coding style

10. Commenting style

11. Comments wanted: iostream code style

12. A new C comment style

 

 
Powered by phpBB® Forum Software