Arduino comment-o-matic

I was thinking wouldn't it be nice to have a kind of program which adds comments automatically to the code written by the user?
I know there are many custom libraries and it's to much work for the developers of arduino to comment every custom function. But why not make also a program which let you modify the file containing the basic comments?

Why would this be helpful? First, comments placing takes time, time that can be used to develop other useful stuff. Second, the arduino code's become more 'universal' everyone will understand someone's code much better. Third, it will increase the learning process of a beginner arduino programmer.

I don't know if it exist already. I googled and stumbled on nothing. The idea is from a macro explainer from the MMORPG World of Warcraft. See http://www.macroexplain.com/ for further reference.

That would be very nice, but the program should understand the code on semantic level which makes it almost impossible to do.
But please prove me wrong on this one :slight_smile:

I think it would work like this.
if it sees for example this line:

digitalWrite(ledPin, HIGH);

that he will insert beneath this line:

//Write a HIGH value to the digital pin (ledPin)

For example:
digitalWrite(ledPin, HIGH);
//Write a HIGH value to the digital pin (ledPin)

The comments would be based on the function, variable, value,...

digitalWrite(ledPin, HIGH);

[function]([variable name], [value]);
//[short description of function] [value] to [variable name]

That's the concept which I've in mind.

it would not add value to the code for someone who has a few weeks of experience as it just is semantically identical to the code.

How would you auto comment this? [hint: Semantically I intended to make a dice that throws even or odd.]

int x = random(1,6);
switch(x)
{
case 1:
case 3:
case 5: Serial.println("odd"); break;
default: Serial.println("even"); break;
}

The difficulty in the example above is that the switch has a fall through and that there is nowhere a concept of a dice.

And what to do with user defined functions?

I would like it very much if programmers take the time to give the variables used an functions good names, then the code is almost self explaining,

(my opinion)
Rob
PS, I think an auto commenter would be a very nice exercise in patternmatching and string handling so I am not totally against it..

I wouldn't have a problem if I still need to add comments. But there are many functions which my example or a variation of it can be applied to it.

GlennTech:
I think it would work like this.
if it sees for example this line:

digitalWrite(ledPin, HIGH);

that he will insert beneath this line:

//Write a HIGH value to the digital pin (ledPin)

For example:
digitalWrite(ledPin, HIGH);
//Write a HIGH value to the digital pin (ledPin)

The comments would be based on the function, variable, value,...

digitalWrite(ledPin, HIGH);

[function]([variable name], [value]);
//[short description of function] [value] to [variable name]

That's the concept which I've in mind.

This is pretty useless if you ask me.

Writing comments is as important (for different reasons) as writing code. I don't trust my computer to write code for me, why would I trust it to write my comments?

Imagine this:

int doSomethingWeird(int var) {  
    var = (var <<8) & 0xf0;       //WHAT WOULD THE COMMENTS BE ON THIS LINE???
    return var;
}


void loop() {
int ret = doSomethingWeird(6); //WHAT WOULD THE COMMENTS BE ON THIS LINE???

}

So, what would your program put on those lines?
Commenting every single line of your code is going to make your code tiring to read mainly because if a comment is in the code, it normally is there to inform us of something. So if you put a comment on every line, it would take you two times longer to go through a page of code than it would with comments in the right place.

But, hey, we already talk to computers so I may be proved wrong about this. And if I do, I will be happy. :slight_smile:

I know there are documentation generators for c, c++,... I think it's similar to a 'comment generator'.

I know there are documentation generators for c, c++,... I think it's similar to a 'comment generator'.

documentation generators I know of are fetching human made comments from the code and combine that e.g. into helpfiles.

e.g. - Javadoc - Wikipedia - .NET has something similar

Some IDE provide automatic templates for the javadoc comment style, they see the number and type of the parameters and the return type. These can be filled automatically and the programmer completes the comment to a "high" enough level.