Did you guys know about those tools which can analyse code automatically or semi-automatically and generate a HTML file which doccuments it ?
Well I have to do something like that at work, but to be honest...
I don't like it.
My reasons are the following :
1) It doesn't document the code at all, but just gives an overview of functions' name and variables names, etc...
While it's true an overview is nice to have, you can use CTRL+F for very similar resules, and this is not needed if the names were picked in an appropriate way
2) You have to add extra gibberish things around your comments. This actually makes the comments in some way less readable.
Something like :
is more weighty and less readable than
I lack a 3) argument, but anyways, I think this tool was made by bad coders (tm) who were not able to self document their code, and claim they work very professionally.
I'd like to hear you guy's opinion. At first it sounds like a good idea, but overall I've mixed feeling about it...
PS : I had to touch up some existing source code from some other company (I'm not too sure where it's from) and it's definitely the worst program I've ever seen. A part of it was 25+ times the same thing copied and pasted over and over with only a very minor change.
(and it had nothing to do with assembly unrolled for speed, before anyone would mention this)
Well I have to do something like that at work, but to be honest...
I don't like it.
My reasons are the following :
1) It doesn't document the code at all, but just gives an overview of functions' name and variables names, etc...
While it's true an overview is nice to have, you can use CTRL+F for very similar resules, and this is not needed if the names were picked in an appropriate way
2) You have to add extra gibberish things around your comments. This actually makes the comments in some way less readable.
Something like :
Code:
/****f* /main/wathever
* NAME
* wathever
* DESCRIPTION
* This function does XXXX
* SOURCE
*/
* NAME
* wathever
* DESCRIPTION
* This function does XXXX
* SOURCE
*/
is more weighty and less readable than
Code:
/* This function does XXX */
I lack a 3) argument, but anyways, I think this tool was made by bad coders (tm) who were not able to self document their code, and claim they work very professionally.
I'd like to hear you guy's opinion. At first it sounds like a good idea, but overall I've mixed feeling about it...
PS : I had to touch up some existing source code from some other company (I'm not too sure where it's from) and it's definitely the worst program I've ever seen. A part of it was 25+ times the same thing copied and pasted over and over with only a very minor change.
(and it had nothing to do with assembly unrolled for speed, before anyone would mention this)