C++

Forum

 
Methods documentation style

rudiHammad (19)
Hello,

I have been writing code in python for years, and I really like how the documentation of the methods go inside of the body it self.
I see that in C++ the style is to put it outside which is something that I really don't like. I find it polutes the files. And yes you can collapse it, but then you have on top of each method the collapsed syntax.

If it is inside, from my point of view it is cleaner. This is very subjective of course, but I wonder if it is "acceptable" to put the methods documentation inside of the body. What are your thoughts/experience about that topic.

cheers,
R
Last edited on
Duthomhas (13206)
There is no rule. Do it how you like. Just be consistent.

I personally agree with you. I think documentation should follow the object it is documenting.

Unfortunately we are the minority.

A large amount of code in C and C++ is documented using Doxygen. That might be a good starting point for what people will expect to see in your code.

And it really isn’t difficult to get used to.
jonnin (11437)
visual studio is pretty smart about applying comments to names so that mouse over the name gives the comment back in the pop up. If that is working, I am happy. But there are multiple tools that work off very specific formats which can then construct a form of documentation or other data about the code. If your company or project or whatever are using such a tool, you have to follow that format exactly. If not, you can do what you like.
rudiHammad (19)
Coming back to this topic, is it possible that the reason why the standard way of writing the docstring above the method is because many of the method members are not defined in the header files(meaning the don't have a body {}). So if there is no body necesarrily the documentation goes above in the header file. Which will keep clean the source files without any documentation since this is done in the header files.
jonnin (11437)
they always have a body. They do not always have a prototype/forward declare/header/whatever words you want for that part.
that body may be in the header:

class foo
{
//bar explains the universe to the caller with nothing in the .cpp file
int bar(){return 42;}

classes & OOP didn't do much here.
procedural programming worked the same way, you may or may not have the .h prototype part, but you always had the body. The prototypes tell the compiler that it exists and what it will look like, the body will be compiled and do the work, whether its in an object or not.

but that aside ... there are many reasons.
you often distribute a header file but not the implementation file to users esp for a library, so documenting the .h file makes sense in that case. The implementation can be in the .h file, and documenting there makes sense again. The only place where documenting in the header does not make sense, then, is procedural programming where the function has no entry in the .h file. This just isnt done outside of 1 page homeworks/hack programs: you would make the entry and document it in the h file anyway. So, in short, it makes sense to doc in the .h file for at least those two reasons. Templates are a third reason, as they have no cpp file. There may be other reasons too, but across the board, see how it makes sense to put it there?
Last edited on
rudiHammad (19)
This is what I meant with "no body"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
#include <iostream>

// This would be the header just declaring the methods, not defining them, so no body.
class Foo
{
public:
    void hello();
    int year();
};


// This would be the source file where you define methods, so it where you set body
void Foo::hello() {std::cout << "how you doing?? \n"; };
int Foo::year() {return 1908; };


int main() {
    // Write C++ code here
    Foo foo;
    foo.hello();
    auto y = foo.year();
    printf("%i \n", y);

    return 0;
}



The example above is how I see many api written. So the header just declares without the body. And the source defines it, which is is cool. My problem is just visual, because this is how a the documentation eats the readability.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
class Foo
{
public:
    /**Brief description.
    *
    * Some extendend description on what it does.
    *
    * @param name, the name of whatever.
    * @param age, some number.
    * @nationality, where you are born buddy.
    */
    void hello(std::string name, int age, std::string nationality);

    /**Brief description.
    *
    * Some extendend description on what it does.
    *
    * @param name, the name of whatever.
    * @param year, some number.
    */
    void bye(std::string name, int year);
    
};


I see that in a lot of APIs. I thing documentation is really important, but that style really makes it hard to read. I don't know, I guess at least it can be collapsed...
Last edited on
kbw (9488)
Documentation? Not seen that in a while, didn't know it was still a thing.
jonnin (11437)
yes, it can be hard to read. I have, on top of grep, 3 or 4 half page text file tools I wrote to deal with such annoying things. One of them keeps lines that have user provided text in them, eg keep file.h ; class ... would more or less remove most of the comments and get close enough for a quick study, leaving the original intact if I need to look up something that wasn't pulled. Grep would probably do it all without the others, but I am not that slick with REs.
Topic archived. No new replies allowed.