StyleGuide needs a section on comments

[nwolek]

This file: https://github.com/jamoma/Jamoma/blob/dev/Doxygen/intro_chapters/C-StyleGuide.dox

Shows up on the web here: http://api.jamoma.org/appendix_styleguide.html

We should mention:

• In general, comments should emphasize not "what" the code is doing, but "why" the code is doing it
• Doxygen used documentation. Connection with api website and IDE integration

[lossius]

Hi Nathan,

I did some work on this a few days ago, and you can see the result here:

http://api.jamoma.org/appendix_styleguide.html

Could you please check if this is good enough for now, or eventually add stuff that you're missing? I believe this issue is mostly done and almost ready to be closed.

Thanks, Trond

[nwolek]

A great addition. Thanks, Trond!

1) Re your guidance on brief: "\@brief - single sentence typically starting by the module name"

I thought we agreed in Bergen that starting with the module name was redundant. I would rather they start with a verb.

2) It would be good to embed real code examples into this chapter via the @snippet tag. You can see that I did this in the 60-UnitTesting.dox chapter. This way when the actual code is updated, it is automatically updated in the Doxygen chapter.

If you want me to handle this, you can make a ticket and assign to me.

-Nathan

On May 8, 2014, at 3:22 PM, Trond Lossuis notifications@github.com wrote:

Hi Nathan,

I did some work on this a few days ago, and you can see the result here:

http://api.jamoma.org/appendix_styleguide.html

Could you please check if this is good enough for now, or eventually add stuff that you're missing? I believe this issue is mostly done and almost ready to be closed.

Thanks, Trond

— Reply to this email directly or view it on GitHub.