Methods documentation style


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.

Last edited on
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.
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.
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.
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
Registered users can post here. Sign in or register to post.