What code commenting style should I use for both C++ and C# ?

views:

187

answers:

+2 Q:

What code commenting style should I use for both C++ and C# ?

Hi,

I was recently hired in a company. They have a lot of C++ and C# code source files and almost one different commenting style per file. (Well this is exagerated, but you have the picture)

This morning, I show my new collegues how my personnal code was commented and how easy it was to generate a documentation from it (I use Doxygen). I somehow convinced them to use a coherent commenting style.

I would suggest using Doxygen for C++ source files and native C# style commenting style for C# files. However, I'm not sure that's the best solution here.

Are you aware of a commenting style that would work for both C++ and C# allowing us to generate a documentation from it ? If so, what software/tool should we use ?

Having a solution that would work on Linux platforms as well would be even better.

Thank you very much.

+3 A:

I would use Doxygen for C# and C++.

Last time I looked Doxygen worked on Linux so I don't see the point of your last question.

graham.reeds 2010-04-21 09:40:58

Thanks. I my last question was probably bad expressed : I just wanted to say that if someone provides another solution, I would be great that it works also on Linux, just like Doxygen does.

ereOn 2010-04-21 12:03:57

+3 A:

I would suggest using Doxygen for C++ source files and native C# style commenting style for C# files. However, I'm not sure that's the best solution here.

Doxygen can generate documentation out of native XML C# style, so this is the way to go. Using the native C# syntax gives you the advantage of intellisense on these in visual studio - and doxygen still understands it.

Go for native doxygen for C++. (Personally I like the @ style instead of the \ style for c++ - e.g. @param vs \param )

nos 2010-04-21 09:46:08

I use the @ style too for my code.

graham.reeds 2010-04-21 09:50:25

We also use @param. +1

JBRWilkinson 2010-04-21 10:13:11

Thanks for your advices. Could you please give me more information about Doxygen and C# ? I'm not sure to get you (english is not my mother language)

ereOn 2010-04-21 12:08:11

I'm just saying you can continue to write comments in your c# code as described here: http://msdn.microsoft.com/en-us/library/b2s063f7.aspx , run doxygen on your c# code and it will generate documentation for you.

nos 2010-04-21 12:17:54

Doxygen: http://www.doxygen.org/

Jason Williams 2010-04-22 12:11:20

+2 A:

The approach that works best in my experience is to not conflate comments and documentation. Documentation is not, and can not be generated from comments.

Documentation is written. As prose. In text, with paragraphs and sentences.

Comments, on the other hand are written inside the source code, as brief notes to explain tricky parts of the code to a maintainer.

And trying to put 15-line "comments" above every function describing their use just bloats your code files and adds a lot of noise. Put those descriptions in the documentation instead. Write an actual document containing your documentation, and use comments only for comment-like things. A single line here and there just to clarify specific code snippets.

When you go the Doxygen route, you almost always end up with "documentation" which tells you that the function "CreateFoo(int i, float j)" is a function which creates a foo, and takes an int and a float.

In other words, nothing you didn't already know.

jalf 2010-04-21 11:55:39

I understand your point and I have to admit it makes sense.

ereOn 2010-04-21 12:06:54

I agree, but note that literate programming *is* possible with discipline and this basically means putting documentation in prose into the code itself.

Konrad Rudolph 2010-04-21 12:08:34

I've found structured comments an invaluable source a year down the line.

graham.reeds 2010-04-21 14:05:03

@Konrad: Agreed, but you also end up with a lot of noise in your source code: when I'm looking at the code, I tend to want to have as much code on screen as possible. 20 lines of documentation interleaved with the code kind of interferes with that. ;)But you're right, of course, if you're disciplined it can work. I guess my main point is that documentation is not, and can not be generated from, comments. As long as you're clear on that point, you can put the documentation wherever you like, even in the source code. You just have to be clear on what's comments and what's documentation.

jalf 2010-04-21 16:14:14

@graham.reeds: No, what you've found useful is the information they contained. And I'm certainly not arguing that this information should not exist. Just that it should be considered documentation, rather than comments, and be written as such.

jalf 2010-04-21 16:16:34

@jalf: External documentation (design docs, etc) is different from code documentation and code comments. It's much easier to keep code docs in sync, and refer to the docs if they are *in* the code they refer to. If your code documentation says "MakeBanana will make a banana" then the *symptom* is poor documentation, but the *cause* is bad programmers doing their job poorly. If you think code docs are "noise" then you are writing/using your code docs incorrectly - they should summarise the code so that you don't have to read someone's code to understand what it does or call their methods.

Jason Williams 2010-04-22 12:20:05

@Jason: No, I think in-code docs are "noise" because they don't tell me what I want to know *when I'm looking at the code*. When I'm looking at the code, it's because I want to see the code. If I don't want to see the code, but simply want to understand how to use it, I look in external docs. Which have, hopefully, been written to explain this. If you think the only external documentation should be stuff like design docs (that is, stuff written to aid the implementation of the library, rather than the *use* of it), I really really don't want to work with your code.

jalf 2010-04-22 13:04:22

The in-code comments should tell you what you want to know when looking at the code. It shouldn't tell you what the code already tells you, and it shouldn't waste valuable screen space telling you things that aren't relevant *when you're reading the code*. If it's something you need to know at other times (when *using* the code, for example), put it elsewhere. What I want to see in the code itself is the information relevant to someone maintaining the code, because if I'm reading the code, it's presumably because I'm maintaining it, rather than trying to *use* it.

jalf 2010-04-22 13:07:47

@jalf: I agree with you about telling you what you need to know when looking at the code. In-code docs should define the full "contract" for a method (e.g. "parameter 'buffer' may not be null", "XyzException will be thrown when..."). This is vital info for the caller as well as the maintainer of the code, and is *not expressed* in the code itself. In addition, by storing it inline, it is available when and where it is needed (next to the relevant code and in intellisense when calling the code) - much better than external docs. If you don't want to look at this while coding, use outlining?

Jason Williams 2010-04-22 15:47:38

+1 A:

I'd also suggest using DocXml for both (as Doxygen supports XML, you get the best of both worlds).

In addition, take a look at my free AtomineerUtils add-in for Visual Studio. It automates the generation and update of documentation comments and automatically reformats the comment into your configured style, which (apart from saving loads of time) enforces one consistent style across the project.

It can also convert existing Doxygen/DocXml comments so it's easier to update legacy comments to your single new format.

Alternatively, if you decide you want to use DocXml in C# and Doxygen in C++, AtomineerUtils handles both formats equally well (and can auto-detect the format used in each file from its file header), so you can still use it to enforce a consistent layout/style even if you use different base commenting format in each language.

Jason Williams 2010-04-22 06:19:27

Thank you very much for the alternative. I will take a look !

ereOn 2010-04-22 06:26:38

ansaurus

tags:

views:

answers:

What code commenting style should I use for both C++ and C# ?

related questions