I actually like doxygen, and use doxygen formatted comments religiously. It does take a rather large amount of discipline to keep straight, so I do have a few practices I keep to.
Firstly, I'm also really disciplined about proper naming conventions and literate programming. This alone goes a long way to reducing the amount of documentation needed, and has the side effect that what documentation you do need can stay at a higher-level -- e.g. if it's clear which variables and parameters are vectors, you can speak generally of vectors, rather than being tempted to use variable names (this is part of the earlier advice of "don't repeat yourself").
That said, you want to keep on-topic. I use doxygen comments only for API reference documentation. Conceptual material, how-tos and examples longer than a line or two belong in external documentation, not inline documentation.
The last thing I do is that I refrain from documenting until I'm reasonable certain that a section of code is stable. This way you don't repeat too much work when things change. You also have to be vigilant to ensure comments remain up-to-date in the face of new features or bug-fixes, so consider the documentation as a bug whenever things change until you've reviewed its accuracy.
Fancy C++ comments.
Quote:Original post by flodihn
For example this would be a good comment:if(vertexCount <= 0) { // Easy memory leak here if we forget to delete mFaces before returning. delete[] mFaces; return;}
And this would be a bad comment:if(vertexCount <= 0) { // Freeing up faces. delete[] mFaces; return;}
Both comments say exactly the same thing, in which I prefer the _second_ one, since it is much more compact and to the point. It is namely obvious that we leak if we don't delete and obvious that the action is done before returning.
I only ever comment when I view the code for the second time and don't get what is going on. This OFTEN is at spots where I've done optimization. Optimization obfuscates the code, so comment at spots where you optimize the code!
For the rest, beside that I don't use Doxygen, I totally agree with Ravyne.
Quote:Original post by DecriusQuote:Original post by flodihn
For example this would be a good comment:if(vertexCount <= 0) { // Easy memory leak here if we forget to delete mFaces before returning. delete[] mFaces; return;}
And this would be a bad comment:if(vertexCount <= 0) { // Freeing up faces. delete[] mFaces; return;}
Both comments say exactly the same thing, in which I prefer the _second_ one, since it is much more compact and to the point. It is namely obvious that we leak if we don't delete and obvious that the action is done before returning.
They don't say anywhere near the same thing. Second comment is redundant, as it says what is written in the code, and nothing else. First code explains why the code is written. It is not at all obvious that there will be a memory leak if the pointer is not release, because it can be owned by something else that is responsible for releasing it at the appropriate time. That is not obvious from the posted piece of code.
Understanding why something is done is important, and not something that can be conveyed easily in code sometimes.
Quote:Original post by Brother Bob
They don't say anywhere near the same thing. Second comment is redundant, as it says what is written in the code, and nothing else. First code explains why the code is written. It is not at all obvious that there will be a memory leak if the pointer is not release, because it can be owned by something else that is responsible for releasing it at the appropriate time. That is not obvious from the posted piece of code.
Yes it is. If it IS owned by something else, the whole code wouldn't exist and no comment would be placed. If it IS NOT owned by something else (self-owned), then the code DOES exist and it is obvious. So the existence of the deletion code is is telling you already: not deleted memory leaks (in this case), memory is owned by self, we do this before returning.
Now if the case would be that the deallocated memory is owned by something else, but is deleted here, a comment might come in handy. Or when something out of the usual goes on...the code presented is actually fairly common code.
Besides, if it IS worth commenting, the first comment should be more to the point IMO.
Quote:Original post by Brother Bob
Understanding why something is done is important, and not something that can be conveyed easily in code sometimes.
True.
Quote:Original post by Decrius
Yes it is. If it IS owned by something else, the whole code wouldn't exist and no comment would be placed. If it IS NOT owned by something else (self-owned), then the code DOES exist and it is obvious. So the existence of the deletion code is is telling you already: not deleted memory leaks (in this case), memory is owned by self, we do this before returning.
I apologise in advance if I've misunderstood, but does RAII not make this moot?
I don't really understand the question above but the closest quandry I've ever had was solved by making use of the language's built in support for construction and destruction of local objects.
Sorry if I'm missing a more subtle point.
Quote:Original post by flodihn
For example this would be a good comment:
The focus is good, but the content is not. A C++ coder has no business editing such code while not knowing that we delete[] because "leaks are bad, mkay?" -- which is what the content boils down to. It's not like you're going to "forget" to delete[] "mFaces" "here" when you've already done it!
You might forget to delete something else, or delete mFaces someplace else, or some oddity of the surrounding code might make people think they should actually remove the delete[] -- but none of these issues are well addressed by the comment.
I'd rather know, say, why we have an early bailout (performace? later code that would crash with vertexCount==0?), or why we're not using RAII (even if only the implied "I'm too lazy to fix this" of a "// TODO: Use RAII instead")
There are a number of reasons to add a comment into code.
1) As a reminder to yourself.
2) To explain a rather odd function to someone else.
3) To tell someone else reading your code something very important.
4) Documentation.
The initial posters comment block is one which is likely used for documentation purposes. Programs like Nautral Docs, and Doxygen read these comments and generate HTML and .chm help files which can help somewhat automate the process of documentation.
Is it a good idea? I suppose it depends, if your doing things just for yourself then it might be a good practice, but you won't see huge benefits out of it. If your writing a third party library then it can provide some assistance in generating documentation for function that the library users will want to use. And if your working in a company with other programmers then these types of comments are extremely useful when anyone new gets hired, or is working in an area of the code that is unfamiliar.
The downside to these style comments is that when you refactor your code you MUST make certian to update the comments. Fortunately things like Visual Assist help automate that process as well.
For future reference you can look at : http://www.possibility.com/Cpp/CppCodingStandard.html
This is a pretty good document on coding style guidelines. It's more of a good practices guideline than a "how to" book though.
1) As a reminder to yourself.
2) To explain a rather odd function to someone else.
3) To tell someone else reading your code something very important.
4) Documentation.
The initial posters comment block is one which is likely used for documentation purposes. Programs like Nautral Docs, and Doxygen read these comments and generate HTML and .chm help files which can help somewhat automate the process of documentation.
Is it a good idea? I suppose it depends, if your doing things just for yourself then it might be a good practice, but you won't see huge benefits out of it. If your writing a third party library then it can provide some assistance in generating documentation for function that the library users will want to use. And if your working in a company with other programmers then these types of comments are extremely useful when anyone new gets hired, or is working in an area of the code that is unfamiliar.
The downside to these style comments is that when you refactor your code you MUST make certian to update the comments. Fortunately things like Visual Assist help automate that process as well.
For future reference you can look at : http://www.possibility.com/Cpp/CppCodingStandard.html
This is a pretty good document on coding style guidelines. It's more of a good practices guideline than a "how to" book though.
Quote:Original post by DecriusQuote:Original post by Brother Bob
They don't say anywhere near the same thing. Second comment is redundant, as it says what is written in the code, and nothing else. First code explains why the code is written. It is not at all obvious that there will be a memory leak if the pointer is not release, because it can be owned by something else that is responsible for releasing it at the appropriate time. That is not obvious from the posted piece of code.
Yes it is. If it IS owned by something else, the whole code wouldn't exist and no comment would be placed. If it IS NOT owned by something else (self-owned), then the code DOES exist and it is obvious. So the existence of the deletion code is is telling you already: not deleted memory leaks (in this case), memory is owned by self, we do this before returning.
I'm not concerned about this example in particular, which in itself is kind of a bad example, but about the general idea of commenting intent and not action. First code comment intent, second code comment action. My argument is not in regards to this code, but in general.
Author
I'm not trying to make my code readable since I plan to be the only one working on it and it will be closed source. I'm just going to provide the library as an easy to use simple 3D game engine that can pretty much do anything. I was writing the comments as an in compiler documentation. I did this mainly because I thought if I were using the API and could get full documentation while programming with the API instead of needing to find the documentation online it would be better.
Quote:Original post by SteveDeFacto
I'm not trying to make my code readable since I plan to be the only one working on it and it will be closed source.
I'd say you're making a (beginners) mistake here. You will hate yourself next week / next month / next year when you need to refactor code you wrote now with the intend "I'm the only one working on it, so readability is no concern", because the speed is horrible and the features limited, and the client wants the product in 2 weeks and you have no time to rewrite it all, but it's such a mess!...
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
