Commenting style 
Author Message
 Commenting style

Hello everyone,

I want to know whether we have standard styles for writing
comments in C programs, just as we have coding styles. Thanks.

--
God is real, unless declared integer. - Anonymous



Tue, 03 May 2005 23:56:24 GMT  
 Commenting style

Quote:
> I want to know whether we have standard styles for writing
> comments in C programs, just as we have coding styles. Thanks.

/* good */
whatever;

whatever /* bad */

/* bad 1 */
/* bad 2 */

/* good 1
   good 2 */

/* good 1
 * good 2
 */

/*
 * good 1
 * good 2
 */

/*
** good 1 (but too heavy to me)
** good 2
*/

I also use (automagically generated by my editor):

/* ---------------------------------------------------------------------
   (c) Emmanuel Delahaye 2002
   (c) AETA 2002
   Project      :
   Function     :
   Module       :
   File         :
   Created      : 15-11-2002
   Modified     : 15-11-2002
   --------------------------------------------------------------------- */

/* ---------------------------------------------------------------------
   Log

   0.0 - 15-11-2002 Created

   --------------------------------------------------------------------- */

/* macros ============================================================== */
/* constants =========================================================== */
/* types =============================================================== */
/* structures ========================================================== */
/* private variables =================================================== */
/* private functions =================================================== */
/* internal public functions =========================================== */
/* public variables ==================================================== */
/* entry points ======================================================== */
/* ---------------------------------------------------------------------
   f()
   ---------------------------------------------------------------------

   ---------------------------------------------------------------------
   I:
   O:
   --------------------------------------------------------------------- */

--
-ed- emdel at noos.fr ~]=[o
FAQ de f.c.l.c : http://www.isty-info.uvsq.fr/~rumeau/fclc/
C-library: http://www.dinkumware.com/htm_cl/index.html
"Mal nommer les choses c'est ajouter du malheur au monde."
-- Albert Camus.



Wed, 04 May 2005 02:32:48 GMT  
 Commenting style

Quote:

> Hello everyone,

> I want to know whether we have standard styles for writing
> comments in C programs, just as we have coding styles. Thanks.

"We" have no common coding styles, as has been amply proven by the
various lengthy discussions on this topic.

If you are working in a professional environment, such standards should
be agreed upon or dictated. If you are working on your own, then you
should work out a system that makes sense to you as you revist code that
you haven't worked on in some time.

A few rules:

1. Avoid too many comments.
2. Avoid too few comments.

Brian Rodenborn



Wed, 04 May 2005 02:35:22 GMT  
 Commenting style

Quote:


> > I want to know whether we have standard styles for writing
> > comments in C programs, just as we have coding styles. Thanks.

> /* good */
> whatever;

Why is this good?

Quote:

> whatever /* bad */

Why is this bad?

Quote:

> /* bad 1 */
> /* bad 2 */

Why is this bad?

Quote:

> /* good 1
>    good 2 */

Why is this good?

Quote:

> /* good 1
>  * good 2
>  */

Why is this good?

Quote:

> /*
>  * good 1
>  * good 2
>  */

Why is this good?

Quote:

> /*
> ** good 1 (but too heavy to me)
> ** good 2
> */

Why is this good?

<snip>

--

"Usenet is a strange place." - Dennis M Ritchie, 29 July 1999.
C FAQ: http://www.eskimo.com/~scs/C-faq/top.html
K&R answers, C books, etc: http://users.powernet.co.uk/eton



Wed, 04 May 2005 04:34:36 GMT  
 Commenting style

Quote:
>> /* good */
>> whatever;

> Why is this good?

You are too curious :-)

I prefer to place the comment above the object. It allows a longer line,
and it it easy to maintain, copy or remove.

Quote:
>> whatever /* bad */

> Why is this bad?

The end of line comment is a nightmare :

- makes lines too long
- what if you need 2 lines?

whatever; /* xxxxxxx
xxxxxxxx */

or

whatever; /* xxxxxxx
             xxxxxxxx */

Too ugly to me...

Quote:

>> /* bad 1 */
>> /* bad 2 */

> Why is this bad?

Maintenance nightmare. Because we are writing from left to right, the right
size must stay 'opened'.

Quote:

>> /* good 1
>>    good 2 */

> Why is this good?

Mmmm, say, better. Not really good. Easier to maintain
(the right size is nearly opened )

Quote:

>> /* good 1
>>  * good 2
>>  */

> Why is this good?

Fully right opend.

Quote:
>> /*
>>  * good 1
>>  * good 2
>>  */

> Why is this good?

I meant

/*
 * good 1
 * good 2
 *
 */

Ditto. Some people like air, hence the blank lines.

Quote:
>> /*
>> ** good 1 (but too heavy to me)
>> ** good 2
>> */

> Why is this good?

It looks fine, but it's a little harder to maintain (add two '*' instead of
one per new line). Well, finally, no that difficult.

Quote:
> <snip>

I'm sad. No more question about my personal C-code skeleton?

--
-ed- emdel at noos.fr ~]=[o
FAQ de f.c.l.c : http://www.isty-info.uvsq.fr/~rumeau/fclc/
C-library: http://www.dinkumware.com/htm_cl/index.html
"Mal nommer les choses c'est ajouter du malheur au monde."
-- Albert Camus.



Wed, 04 May 2005 04:47:15 GMT  
 Commenting style


Quote:

>> Hello everyone,

>> I want to know whether we have standard styles for writing
>> comments in C programs, just as we have coding styles. Thanks.
...
> 1. Avoid too many comments.

for instance, avoid comments such as

int i = 5; /* initialize integer variable i to 5 */

not because of the placement of the comment, but because it explains
nothing more than what is obvious from the code, and makes is hard to
maintain.

--
A. Sinan Unur

Remove dashes for address



Wed, 04 May 2005 05:11:03 GMT  
 Commenting style

Quote:

> Hello everyone,

> I want to know whether we have standard styles for writing
> comments in C programs, just as we have coding styles. Thanks.

Yep, we have:

If it was hard to write, it should be hard to read.

Aka the no commenting rule and job security.

--
Thomas.



Wed, 04 May 2005 05:17:24 GMT  
 Commenting style

Quote:


> >> /* good */
> >> whatever;

> > Why is this good?

> You are too curious :-)

No such thing, except for cats.

The point I was trying to make was that style is a personal thing, and
one man's expository meat is another man's obfuscatory poison. We can
legitimately say "I like /this/ commenting style but not /that/ one",
and perhaps give reasons. It is not so legitimate to say "this
commenting style is good, but that one is bad", without /at the very
least/ giving reasons.

Having read your reasons, I agree with some but not all of them. For
example, I have no particular problem with splitting an end-of-line
comment over two or more lines like this:

  f = g + h / i * j; /* get the ratio of hats to indices,
                      * multiply by the jackrabbits, and
                      * add in the gross. This gives you
                      * the total number of footballers.
                      */

although I must admit that this has to count as an exaggeration on my
part!

Quote:

> I prefer to place the comment above the object. It allows a longer line,
> and it it easy to maintain, copy or remove.

Many editors now allow copy, cut and paste of rectangular blocks of
text.

<snip>

--

"Usenet is a strange place." - Dennis M Ritchie, 29 July 1999.
C FAQ: http://www.eskimo.com/~scs/C-faq/top.html
K&R answers, C books, etc: http://users.powernet.co.uk/eton



Wed, 04 May 2005 05:36:25 GMT  
 Commenting style

Quote:




> >> Hello everyone,

> >> I want to know whether we have standard styles for writing
> >> comments in C programs, just as we have coding styles. Thanks.
> ...
> > 1. Avoid too many comments.

> for instance, avoid comments such as

> int i = 5; /* initialize integer variable i to 5 */

unless you are writing a C tutorial. :-)

Quote:

> not because of the placement of the comment, but because it explains
> nothing more than what is obvious from the code, and makes is hard to
> maintain.

Indeed. Nevertheless it has a certain value, in some contexts.

--

"Usenet is a strange place." - Dennis M Ritchie, 29 July 1999.
C FAQ: http://www.eskimo.com/~scs/C-faq/top.html
K&R answers, C books, etc: http://users.powernet.co.uk/eton



Wed, 04 May 2005 05:37:26 GMT  
 Commenting style
in comp.lang.c i read:

Quote:

>>> /* bad 1 */
>>> /* bad 2 */

>> Why is this bad?

>Maintenance nightmare. Because we are writing from left to right, the right
>size must stay 'opened'.

purchase a better editor.

--
bringing you boring signatures for 17 years



Wed, 04 May 2005 06:14:15 GMT  
 Commenting style

Quote:

> Hello everyone,

> I want to know whether we have standard styles for writing
> comments in C programs, just as we have coding styles. Thanks.

Others have provided useful (and not so useful) answers elsethread.

To summarize: No, we don't have standard styles for writing comments,
just as we *don't* have (standard) coding styles.

However, I prefer:

/**********************************************************************
*
* for file headers and multi-line comments describing a large section
* of code
*
**********************************************************************/
<code>

/* -------- for section headers or dividers ------------------------ */
<code>

/* for multi-line comments */
/* describing a small section of code */
<code>

/* for one-line comments describing a small section of code */
<code>

<code>  /* for comments describing a line a code */

I try not to let ragged right edges disturb me too much. If I have the
time and inclination I will add spaces to even them up.

Quote:
> --
> God is real, unless declared integer. - Anonymous

This is old fortran joke (which would make it off-topic here it weren't
part of your sig).

--
Tim Hagan



Wed, 04 May 2005 06:32:18 GMT  
 Commenting style

Quote:

> purchase a better editor.

When the best one comes for free? I mean Emacs of course.
Some people might like Vim. They both do rectangular regions.

--
Thomas



Wed, 04 May 2005 07:32:51 GMT  
 Commenting style


Quote:

>> Hello everyone,

>> I want to know whether we have standard styles for writing
>> comments in C programs, just as we have coding styles. Thanks.

>"We" have no common coding styles, as has been amply proven by the
>various lengthy discussions on this topic.

>If you are working in a professional environment, such standards should
>be agreed upon or dictated. If you are working on your own, then you
>should work out a system that makes sense to you as you revist code that
>you haven't worked on in some time.

>A few rules:

>1. Avoid too many comments.
>2. Avoid too few comments.

 3. Comments should match the code. Don't change just the code!

--
john R. Latala



Wed, 04 May 2005 11:56:09 GMT  
 Commenting style
in comp.lang.c i read:

Quote:

>> purchase a better editor.

>When the best one comes for free? I mean Emacs of course.
>Some people might like Vim. They both do rectangular regions.

i didn't say it'd be expensive.

--
bringing you boring signatures for 17 years



Wed, 04 May 2005 15:16:13 GMT  
 Commenting style
In 'comp.lang.c', those who know me have no need of my name

Quote:

> in comp.lang.c i read:


>>>> /* bad 1 */
>>>> /* bad 2 */

>>> Why is this bad?

>>Maintenance nightmare. Because we are writing from left to right, the
>>right size must stay 'opened'.

> purchase a better editor.

What is better than UltraEdit?

--
-ed- emdel at noos.fr ~]=[o
FAQ de f.c.l.c : http://www.isty-info.uvsq.fr/~rumeau/fclc/
C-library: http://www.dinkumware.com/htm_cl/index.html
"Mal nommer les choses c'est ajouter du malheur au monde."
-- Albert Camus.



Wed, 04 May 2005 16:21:32 GMT  
 
 [ 25 post ]  Go to page: [1] [2]

 Relevant Pages 

1. Commenting style (was: Call for folklore)

2. Commenting Styles

3. DoDont series I: comment style I

4. DoDont series 1: comment style I

5. A new C comment style

6. Commenting style (was: Call for folklore)

7. javadoc style commenting for C code

8. Style comments for beginner

9. Request for comment; Re: Coding style

10. Comments wanted: iostream code style

11. ANSI C style comments

12. Lisp-style comments

 

 
Powered by phpBB® Forum Software