- Forum
- General C++ Programming
- Code Documentation: Basics
Code Documentation: Basics
I have looked around online, and can not come up with a solid answer. I think this may be somthing that is dictated by personal preference, but I digress.
Is there any standard way of documenting code?
if "yes": can you direct me to a resource so I may learn it?
if "no": is there any prefered way to document code? (prefered in the professional realm, by many)
Thanks in advance, I appreciate the help.
It depends and it depends.
It depends on the company (or you, if you are by yourself). You could look up some documentation generators for whatever programming languages. Some of them don't have a "standard", but some of them (like Java) have one that is very widely used.
It depends on the company (or you, if you are by yourself). You could look up some documentation generators for whatever programming languages. Some of them don't have a "standard", but some of them (like Java) have one that is very widely used.
It depends on context.
As a trend I'd say comments are used less than they used to be for internal code. But that's because more effort is put in to making source self-documenting.
Self-documenting
http://en.wikipedia.org/wiki/Self-documenting
Classes, functions, variables are all named so it's clear what they do without need for comments. At least most of the time. Comments are only really used when something is going on that needs additional explanation. You definitely don't write comments like
For APIs which you're publishing to othe teams or the general public, then you do need to document the calls properly. But this is limited to the public headers. For internal use this is normally done using Doxygen or similar, though if you going public it normally gets a going over by a technical author. The downside of heavy Doxygen comments in headers is that the code can sometimes get lost.
You also comment sample code more than normal, but this should be using self-documenting style, too.
When it comes to what style the comments use, using a Doxygen compatible style is a good idea (either JavaDoc or Qt style), as Doxygen is often used for generating documentation from code.
Doxygen
http://www.stack.nl/~dimitri/doxygen/
Andy
As a trend I'd say comments are used less than they used to be for internal code. But that's because more effort is put in to making source self-documenting.
Self-documenting
http://en.wikipedia.org/wiki/Self-documenting
Classes, functions, variables are all named so it's clear what they do without need for comments. At least most of the time. Comments are only really used when something is going on that needs additional explanation. You definitely don't write comments like
|
|
For APIs which you're publishing to othe teams or the general public, then you do need to document the calls properly. But this is limited to the public headers. For internal use this is normally done using Doxygen or similar, though if you going public it normally gets a going over by a technical author. The downside of heavy Doxygen comments in headers is that the code can sometimes get lost.
You also comment sample code more than normal, but this should be using self-documenting style, too.
When it comes to what style the comments use, using a Doxygen compatible style is a good idea (either JavaDoc or Qt style), as Doxygen is often used for generating documentation from code.
Doxygen
http://www.stack.nl/~dimitri/doxygen/
Andy
Last edited on
Topic archived. No new replies allowed.