Documenting your code...
Author
Hi,
I was wondering if there are any resources on the web to help you in methods for code documentation. I'm starting a new projet and would like to document my code.
So any websites or good books?
Thanks in advance!
You might want to use Doxygen. It can create HTML output and other formats. Once you learned and configured it, it's very easy to use.
I'll second Doxygen. It is a nice, simple, tool.
The ONLY gripe I have with it is more with some of people who use it.
DO NOT fall into the group of people who believe "well Doxygen-ed code == documentation".
There are 3 types of code comments you need. And Doxygen can deal with all of them, you just have to remember to put them in the code.
1) For the end user you need documents to point people in the right direction. Most code/libraries has lots of exposed interfaces, each with a purpose. But, the interface to get a minimal working demo is far smaller than all the advanced interface functions in a library. It is really nice to have a directory of sample code and a simple read me at the base of the project to point you in the right direction.
2) Comment the code USAGE. This is what Doxygen code is good at. Everything about the code pops out in a nice document so you can browse all the features.
3) Comment for the other coders. Don't over comment though. Other coders want to see comments for lines that could be confusing. Other coders want large functions delineated up so you know what progress is made as the go down the page (especially what each non-trivial loop or if/switch contains for purpose)
The ONLY gripe I have with it is more with some of people who use it.
DO NOT fall into the group of people who believe "well Doxygen-ed code == documentation".
There are 3 types of code comments you need. And Doxygen can deal with all of them, you just have to remember to put them in the code.
1) For the end user you need documents to point people in the right direction. Most code/libraries has lots of exposed interfaces, each with a purpose. But, the interface to get a minimal working demo is far smaller than all the advanced interface functions in a library. It is really nice to have a directory of sample code and a simple read me at the base of the project to point you in the right direction.
2) Comment the code USAGE. This is what Doxygen code is good at. Everything about the code pops out in a nice document so you can browse all the features.
3) Comment for the other coders. Don't over comment though. Other coders want to see comments for lines that could be confusing. Other coders want large functions delineated up so you know what progress is made as the go down the page (especially what each non-trivial loop or if/switch contains for purpose)
Author
Ok thanks guys, I'll look into Doxygen... Heard alot of good things about it but never got around to using it...
For my C++ projects, I'm using DoxyGen, too. For C#, I'm using the compiler's /xml option with Sandcastle.
In both cases, I have switched to XML documentation comments, eg.
It helps to think of someone else who might one day read over the code, maybe trying to find out how it works in order to extend it or to fix a bug. What are the most important things you want to tell him? How can you make his life as easy as possible?
In the funny side, that someone else will most likely be you, in a few weeks/months/years, depending on your memory and the size of your project :)
Some typical traps I've seen:
- Properties documented like this: "Gets or sets a value that indicates..." - outch! Alright, it is a value and I can get or set it, surprise. Leave out the babbling and tell me what it does! I've seen this quite often from Microsoft programmers ;)
- Documenting the constructor with "Constructor." - very interesting, but I'd rather know when I should call that particular constructor rather than being reminded that it's in fact a constructor I'm looking at.
- Documenting parameters with descriptions like "a string value" - oh fine, that string parameter wants a string value. And what is the value used for?
When you start the habit of documenting your methods, from personal experience, it'll be a real pain at first because you keep thinking about what to write about your new method/class/whatever. It gets much, much better over time, though. After some months of documenting, you'll get a feeling for what people want to know and notice where you're only leaving useless chatter. Soon comments will start writing themselves... almost! ;)
[Edited by - Cygon on January 19, 2009 6:38:57 AM]
In both cases, I have switched to XML documentation comments, eg.
/// <summary>Creates a visual for the specified type of control</summary>/// <param name="controlClass">/// Denotes the kind of control a visual is created for,/// eg. "CheckBox" or "Panel"./// </param>/// <param name="controlName">/// Allows to uniquely identify the control that is requesting a visual,/// eg. "FullscreenCheckBox" or "VideoSettingsPanel"./// </param>/// <returns>A new visual for the specified type of control</returns>Visual CreateVisual(string controlClass, string controlName);It helps to think of someone else who might one day read over the code, maybe trying to find out how it works in order to extend it or to fix a bug. What are the most important things you want to tell him? How can you make his life as easy as possible?
In the funny side, that someone else will most likely be you, in a few weeks/months/years, depending on your memory and the size of your project :)
Some typical traps I've seen:
- Properties documented like this: "Gets or sets a value that indicates..." - outch! Alright, it is a value and I can get or set it, surprise. Leave out the babbling and tell me what it does! I've seen this quite often from Microsoft programmers ;)
- Documenting the constructor with "Constructor." - very interesting, but I'd rather know when I should call that particular constructor rather than being reminded that it's in fact a constructor I'm looking at.
- Documenting parameters with descriptions like "a string value" - oh fine, that string parameter wants a string value. And what is the value used for?
When you start the habit of documenting your methods, from personal experience, it'll be a real pain at first because you keep thinking about what to write about your new method/class/whatever. It gets much, much better over time, though. After some months of documenting, you'll get a feeling for what people want to know and notice where you're only leaving useless chatter. Soon comments will start writing themselves... almost! ;)
[Edited by - Cygon on January 19, 2009 6:38:57 AM]
As for sourcecode comments, intended to be read by yourself or by your fellow programmers, I am of the fraction that likes self documenting code, that is primarily giving appropriate and meaningful names (*), even if you have to type more (but then it avoids typing a comment). Here are some interesting links:
(*) Consider the following:
Without the comments, it is mandatory that you evaluate the CFG to find out what is going on and what is intended. Furthermore, comments want to be maintained, but programmers dislike maintaining comments (in the example, the comments for the function n() are clearly outdated). And this is yet an easy example.
Consider the version without comments:
Clearly, everyone who is in 3d-graphics directly grasps what is intended. Of course the function computeNormal() could need some refactoring in general, but at least we no longer have to guess what is going on + comment maintenance is no longer needed.
As for general coding style, I follow the one of LuxRender: Lux' Coding style Conventions.
(*) Consider the following:
// This one normalises a vector, given by parameter 'vector'.// The normalised version will be the returned value.void n (const vec &A, vec &B) { float const a = a.x * a.x; float const b = a.y * a.y; float const c = a.z * a.z; float const d = a + b + c; float const e = sqrtf (e); float const f = 1.0f / e; B = A * f;}...int main () { vec a; ... vec n; // this will be our normalised version of a. ::n (a, n); // do the normalisation.}Without the comments, it is mandatory that you evaluate the CFG to find out what is going on and what is intended. Furthermore, comments want to be maintained, but programmers dislike maintaining comments (in the example, the comments for the function n() are clearly outdated). And this is yet an easy example.
Consider the version without comments:
void computeNormal (const vector &in, vector &result) { float const xx = a.x * a.x; float const yy = a.y * a.y; float const zz = a.z * a.z; float const sum = xx + yy + zz; float const length = sqrtf (sum); float const inverse_length = 1.0f /length; result = in * inverse_length;}...int main () { vector direction; ... vector normalised_direction; computeNormal (direction, normalised_direction);}Clearly, everyone who is in 3d-graphics directly grasps what is intended. Of course the function computeNormal() could need some refactoring in general, but at least we no longer have to guess what is going on + comment maintenance is no longer needed.
As for general coding style, I follow the one of LuxRender: Lux' Coding style Conventions.
Permit me briefly to dissent.
Doxygen, Javadoc and ndoc are all decent at what they do. The problem is that what they do requires you to do more: specifically, to duplicate your function interfaces in verbose comments so that these naive parsers can extract the information using the equivalent of a regex. Shouldn't static source analysis tools be able to extract your every namespace, class, function and public attribute definition, ready for your elaboration? You end up having to maintain your code and your comments, and it's quite easy for the comments to end up out of sync with the code.
I'm with phresnel: self-documenting code is preferable. And it's really not that hard to write, once you abandon the silly C-isms and identifier restrictions of the past century. If you can have 256-character identifiers and your tools make it easier to type them, then take advantage of that to give them descriptive names. computeNormal (in, result) is good; normalizeVector(vectorToNormalize, normalVectorResult) is better. Code Intelligence (IntelliSense) turns your interface definitions into documentation.
(Some of you can tell that I've been influence by Objective-C selectors and NextStep descriptors [smile]).
By making your code as readable as possible, with its intent generally clear, you can then spend your (limited) time documenting the non-obvious points or constraints due to implementation specifics.
Doxygen, Javadoc and ndoc are all decent at what they do. The problem is that what they do requires you to do more: specifically, to duplicate your function interfaces in verbose comments so that these naive parsers can extract the information using the equivalent of a regex. Shouldn't static source analysis tools be able to extract your every namespace, class, function and public attribute definition, ready for your elaboration? You end up having to maintain your code and your comments, and it's quite easy for the comments to end up out of sync with the code.
I'm with phresnel: self-documenting code is preferable. And it's really not that hard to write, once you abandon the silly C-isms and identifier restrictions of the past century. If you can have 256-character identifiers and your tools make it easier to type them, then take advantage of that to give them descriptive names. computeNormal (in, result) is good; normalizeVector(vectorToNormalize, normalVectorResult) is better. Code Intelligence (IntelliSense) turns your interface definitions into documentation.
(Some of you can tell that I've been influence by Objective-C selectors and NextStep descriptors [smile]).
By making your code as readable as possible, with its intent generally clear, you can then spend your (limited) time documenting the non-obvious points or constraints due to implementation specifics.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
