Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm having trouble structuring my comments at the moment.

I have major sections of the code that, when scrolling through the document, I want to be able to see those stand out.

Examples:

This is a normal comment:

int money = 100; //start out with 100 money

-

This is a comment to emphasize a certain part of the code:

/****** Set up all the money ******/

But I don't like that this isn't very clean. Is there a standard way of setting up this type of a comment?

share|improve this question
2  
That's what modules, classes and method functions are for. Why aren't you using the language itself to provide more structure? –  S.Lott Mar 15 '11 at 19:55
2  
@S.Lott: Sometimes some people want certain comments to be more attention-grabbing than others, to emphasize the importance of a particular variable or method call. There have been times where I wanted to make very important comments in large, bold, red text. –  FrustratedWithFormsDesigner Mar 15 '11 at 20:00
    
Hmm. GeOS let you use the word processor to write your assembly code! You could style your code (comments are the only thing that made sense here) any way you wanted. WYSIWYG editing. It was fun, but a bit too much overhead for most languages. –  Berin Loritsch Mar 15 '11 at 20:12
2  
<blink>Warning this code blinks!</blink> –  zzzzBov Mar 15 '11 at 20:25
add comment

4 Answers

up vote 5 down vote accepted

I usually use top/bottom comments such as:

/**************************************************************************
This is a critical piece of code that controls the temparature of the main
flux capacitor.
***DO NOT CHANGE THIS*** without first getting management approval
and sign-off on form 21-B
**************************************************************************/

I find the long lines of *'s usually get people's attention. If the comments are going to Javadoc or some doc tool that supports italic or bold emphasis (or others), then I take advantage of that. I think Doxygen and NaturalDocs also support emphasizing comment text as bold or italic, but alas, it is not visible as such in the source code like that.

share|improve this answer
    
I hate this, really breaks up the flow of the code, but on the other hand it does do a good job of getting attention. Though im more worried why something as important as changing that isn't covered by a restrictive process but instead by some text that is easy to ignore –  RhysW Jun 3 '13 at 14:25
add comment

I suggest you use some doc markup comment format, such as Doxygen. I find comments that are appended to code are frequently missed. RE: your "normal" comment:

int money = 100; //start out with 100 money

Why 100? That's what you want to answer.

share|improve this answer
add comment

Have you considered any of the:

  • Better class design? [Possibly with an appropriate design pattern?]
  • Shorter methods, well-named methods?
  • Regions? [if you're using Visual Studio]
  • ///TODO and other tokens? [if you're using Visual Studio]
share|improve this answer
add comment

I find that my multi-line comments fall into one of two categories.

  1. Function header
  2. Code explanation.

Function headers at my company approximate the following

/***************************************************
 *
 * functionName - brief synopsis
 *
 * Function description
 *
 * RETURNS:
 *
 * ERRNO:
 *
 * CAVEATS:
 */

Multi-line code explanations tend to use the following format

 /*
  * Sample comment content may include phrasing such as ...
  * The following code does ... yada yada yada
  * Note that it affects or is affected by ... yada yada yada
  * The following table describes ... yada yada yada
  */

One of the key items that grab the attention I find is the left column of * characters. The row of * characters helps differentiate the function headers from the code explanations.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.