Results 1 to 10 of 10

Thread: Code comments

  1. #1
    Join Date
    Jan 2006
    Location
    Ukraine,Lviv
    Posts
    454
    Thanks
    9
    Thanked 27 Times in 27 Posts
    Qt products
    Qt3
    Platforms
    Unix/X11 Windows

    Default Code comments

    HI all!

    Is it good programing style comented class methods in *.h and *.cpp? Or better only in *.h or only in *.cpp?
    I like before every method available in *.cpp write some block with info about this method. But then i must copy the same info in *.h ?

    Any propposition?

  2. #2
    Join Date
    Jan 2006
    Location
    Scandinavia
    Posts
    62
    Thanks
    5
    Thanked 2 Times in 1 Post
    Qt products
    Qt3 Qt4
    Platforms
    Unix/X11 Windows

    Default Re: Code comments

    I believe it is the most common to comment, explain in the declaration of a function i.e. the .h file.

    Also; it is much easier to get an overview of a class if you can read about what the functions does in the .h file.

    Alternatively, if you have the function, abstract, explanation in the .cpp file it would be harder to get an overview over the whole class since the comments are not standing out as much (due to the amount of code)...

    --- Note: It's good programming practice to have comments in .cpp as well, explaining in the code what is being done at specific steps can seriously help one to read and understand what the code does.

    Did I help or only confuse?

  3. #3
    Join Date
    Jan 2006
    Location
    Germany
    Posts
    85
    Thanks
    1
    Thanked 2 Times in 2 Posts
    Qt products
    Qt4
    Platforms
    Unix/X11

    Default Re: Code comments

    I have two types of comments:
    In the header explaining what a method does, parameters, return value... Later doxygen will generate from these comments a nice documentation.
    The other type of comments explains code passages: What I am doing here, sometimes why I'm doing something that way and not the obvious way... These comments help me to understand my own code when I have to read it again some days, months or even years later.
    But try to avoid writing how you are doing something - most of the time reading the code is better.

  4. #4
    Join Date
    Jan 2006
    Location
    Athens - Greece
    Posts
    219
    Thanks
    3
    Thanked 1 Time in 1 Post
    Qt products
    Qt3 Qt4
    Platforms
    Unix/X11 Windows

  5. #5
    Join Date
    Jan 2006
    Location
    Germany
    Posts
    85
    Thanks
    1
    Thanked 2 Times in 2 Posts
    Qt products
    Qt4
    Platforms
    Unix/X11

    Default Re: Code comments

    Quote Originally Posted by yop
    The most important one

  6. #6
    Join Date
    Jan 2006
    Location
    Ukraine,Lviv
    Posts
    454
    Thanks
    9
    Thanked 27 Times in 27 Posts
    Qt products
    Qt3
    Platforms
    Unix/X11 Windows

    Unhappy Re: Code comments

    ok...
    thanks for mooore information but my question is neverless actual

    Where better comment the method ?

    1) in *.h
    2) in *.cpp
    3) 1) and 2)

    for your replies i see that first choice is better...then when anybody will be research in my code he must always switch betwwen *.h(for look for comments) and *.cpp(for look for implementation)...

  7. #7
    Join Date
    Jan 2006
    Location
    Ukraine,Lviv
    Posts
    454
    Thanks
    9
    Thanked 27 Times in 27 Posts
    Qt products
    Qt3
    Platforms
    Unix/X11 Windows

    Default Re: Code comments

    Quote Originally Posted by Codepoet
    The most important one
    yes i think too

  8. #8
    Join Date
    Jan 2006
    Location
    Germany
    Posts
    85
    Thanks
    1
    Thanked 2 Times in 2 Posts
    Qt products
    Qt4
    Platforms
    Unix/X11

    Default Re: Code comments

    Quote Originally Posted by zlatko
    ok...
    thanks for mooore information but my question is neverless actual

    Where better comment the method ?

    1) in *.h
    2) in *.cpp
    3) 1) and 2)

    for your replies i see that first choice is better...then when anybody will be research in my code he must always switch betwwen *.h(for look for comments) and *.cpp(for look for implementation)...
    I can't tell you what is better, but that my approach works very good for me: Users of my code never read the implementation. They want to know how to use my methods. That's header only. And editors / IDEs can display the comments as little popup windows while writing code
    A maintainer probably already knows how to use the method and jumps directly to the implementation to fix it which should be easier with the comments there which describe what you did.

  9. #9
    Join Date
    Jan 2006
    Location
    Athens - Greece
    Posts
    219
    Thanks
    3
    Thanked 1 Time in 1 Post
    Qt products
    Qt3 Qt4
    Platforms
    Unix/X11 Windows

    Default Re: Code comments

    Quote Originally Posted by Codepoet
    I can't tell you what is better, but that my approach works very good for me: Users of my code never read the implementation. They want to know how to use my methods. That's header only. And editors / IDEs can display the comments as little popup windows while writing code
    A maintainer probably already knows how to use the method and jumps directly to the implementation to fix it which should be easier with the comments there which describe what you did.
    So I'd say that it depends on the final product. If you 're writing a library that other devs will use (probably in a binary form) then writing the comments in the header files (and in doxygen format) is better. If you are writing code that will be maintained / reviewed many times you should go with the comments in the cpp file. Anyway, out of habbit I guess, in my final (beta and up) releases I have doxygen style comments in almost all of my header files.

  10. #10
    Join Date
    Jan 2006
    Location
    Ukraine,Lviv
    Posts
    454
    Thanks
    9
    Thanked 27 Times in 27 Posts
    Qt products
    Qt3
    Platforms
    Unix/X11 Windows

    Default Re: Code comments

    Ok guys Big thanks)

    I use doxygen so my final decision is :
    *.h - input only brief description for class methods
    *.cpp - input detailed description

    I think this method wiil be readability for users and for developers

Similar Threads

  1. How to put custom handle image in QSlider using code?
    By montylee in forum Qt Programming
    Replies: 6
    Last Post: 29th January 2009, 20:38
  2. copyright and gpl
    By janus in forum General Discussion
    Replies: 8
    Last Post: 21st October 2008, 02:13
  3. Qt Cryptographic Architecture
    By vermarajeev in forum Qt Programming
    Replies: 6
    Last Post: 9th February 2007, 14:15
  4. Problem closing a QMainWindow in Qt4.2
    By ian in forum Qt Programming
    Replies: 11
    Last Post: 17th October 2006, 01:49

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •  
Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide.