Thread: method commenting

  1. #1
    Registered User
    Join Date
    Feb 2006
    Posts
    58

    method commenting

    Hi,i got a method

    Code:
    void searchStaff(string staffID){
    }
    I want to write a comment on top to describe the method.

    i did this:

    Code:
    /*searchStaff(string staffID) function searches a staff.
    @staffID is id of staff to be found*/
    
    void searchStaff(string staffID){
    }
    is this correct way to specific wat the method parameter is for?

  2. #2
    Making mistakes
    Join Date
    Dec 2008
    Posts
    476
    I suppose your double-post is a mistake. Maybe make the comment cleaner and separate explanation, arguments and the function name. Such as:

    Code:
    /* void searchStaff(std::string staffID): Search staff with ID staffID
       Parameters:
           - staffID: The ID of the staff to be found
    
    ... long explanation here */
    Actually, everything is a matter of personal preference. That was just an example.

    PS: Are you working with global variables? Because search functions normally do return a value.

  3. #3
    Registered User
    Join Date
    Apr 2009
    Posts
    145
    Code:
    /****************************************************************************
     *
     * NAME:  Enable_Device(arguments)
     *
     * DESCRIPTION:
     *          Data message processor callback.  This function processes
     *          any incoming data - probably from other devices.  So, based
     *          on cluster ID, perform the intended action.
     *
     *  Param: pkt - incoming message
     *
     *
     * RETURNS:
     *         none
     *
     ****************************************************************************/

  4. #4
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    28,413
    *Moved to C++ programming forum*

    Quote Originally Posted by rahulsk1947
    I want to write a comment on top to describe the method.
    One approach is to document the pre-conditions and post-conditions of the function.

    Quote Originally Posted by rahulsk1947
    is this correct way to specific wat the method parameter is for?
    If you are using a documentation generation tool that recognises @staffID then yes, that is probably what you can do. On the other hand, the name is reasonably descriptive, so restating the parameter name in a comment does not really add information.

    Aside from Brafil's observation, I note that you most likely should be passing the std::string by const reference.
    Quote Originally Posted by Bjarne Stroustrup (2000-10-14)
    I get maybe two dozen requests for help with some sort of programming or design problem every day. Most have more sense than to send me hundreds of lines of code. If they do, I ask them to find the smallest example that exhibits the problem and send me that. Mostly, they then find the error themselves. "Finding the smallest program that demonstrates the error" is a powerful debugging tool.
    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  5. #5
    and the hat of int overfl Salem's Avatar
    Join Date
    Aug 2001
    Location
    The edge of the known universe
    Posts
    39,660
    Consider making whatever style you go for compatible with say Doxygen
    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. on method pointers and inheritance
    By BrownB in forum C++ Programming
    Replies: 2
    Last Post: 03-02-2009, 07:50 PM
  2. stuck on display method
    By shintaro in forum C++ Programming
    Replies: 2
    Last Post: 02-01-2009, 05:17 PM
  3. Best communication method to thousand childs?
    By Ironic in forum C Programming
    Replies: 8
    Last Post: 11-08-2008, 12:30 AM
  4. C# method
    By siten0308 in forum C# Programming
    Replies: 6
    Last Post: 07-15-2008, 07:01 AM