Thread: comments

  1. #1
    Registered User
    Join Date
    Sep 2001
    Posts
    8

    Question comments

    I'm starting to learn C language and want to include comments in my programs but I'm not sure what parts to comment on and what not to bother with. is there any rule of the thumb?

  2. #2
    Registered User The15th's Avatar
    Join Date
    Aug 2001
    Posts
    125
    Comments are an important role of programming. It is good practace to add comments when your first starting out, then later on when your working on larger programs that require comments for you to understand a few days later, you wont need to think about it because it will be second nature to you. Sometime you can over comment and then its hard to find code from comments. I dont know of any rule, but i generally comment on all functions, classes, varables ect ect, that i have added. If your just starting then i reccomend you comment everwhere eg, #include <fstream.h> //Header File For File I/O
    so you can get used to all the fuctions and headers that c/c++ provide.

  3. #3
    the hat of redundancy hat nvoigt's Avatar
    Join Date
    Aug 2001
    Location
    Hannover, Germany
    Posts
    3,130
    Rule for comments: MORE MORE MORE

    There cannot be enough. If later you think it's too
    much, you can always delete it. If you need more,
    it's very hard to remember when it's too late.
    hth
    -nv

    She was so Blonde, she spent 20 minutes looking at the orange juice can because it said "Concentrate."

    When in doubt, read the FAQ.
    Then ask a smart question.

  4. #4
    and the hat of int overfl Salem's Avatar
    Join Date
    Aug 2001
    Location
    The edge of the known universe
    Posts
    39,660
    > is there any rule of the thumb?
    Comments should tell you something which isn't obvious from looking at the code. You can tell a lot from uncommented code, providing that functions are well named (and well defined), and variables also have meaningful names.

    If your comments are wrong, later readers of your code will simply ignore them, since they're now worthless (or perhaps even dangerous), so choose your words carefully.

    Using the pseudo code from your design (you have a design don't you) is a good starting point, providing its not too detailed.

    Examples...

    This comment is accurate, but useless (tells you nothing extra)
    x = x + 2 ; // add 2 to x

    This is better, tells you why
    x = x + 2 ; // the next even number

    This is an incorrect comment, if you see for instance
    x = 1;
    then....
    x = x + 2 ; // the next even number
    If you dance barefoot on the broken glass of undefined behaviour, you've got to expect the occasional cut.
    If at first you don't succeed, try writing your phone number on the exam paper.

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. removing comments of type '//' and '/*'
    By rohit83.ken in forum C++ Programming
    Replies: 3
    Last Post: 10-20-2007, 02:24 AM
  2. removing comments of type '//' and '/*'
    By rohit83.ken in forum C Programming
    Replies: 2
    Last Post: 10-19-2007, 10:14 AM
  3. program to remove comments from source
    By Abda92 in forum C Programming
    Replies: 12
    Last Post: 12-25-2006, 05:18 PM
  4. comments
    By nightingale in forum C Programming
    Replies: 32
    Last Post: 07-18-2003, 03:49 AM
  5. The Art of Writing Comments :: Software Engineering
    By kuphryn in forum C++ Programming
    Replies: 15
    Last Post: 11-23-2002, 05:18 PM