0

Does anyone know of an easy way for calculating what percentage of types, methods, and properties in a C# project are decorated with XML comments?

I am considering ways of improving on our code documentation. A team I joined a few months ago is not used to adding XML comments to their code, and both myself and other recent joiners have found it hard to get to grips with such poorly documented code. I am planning on proposing to treat this as tech debt that needs to be paid off. I figured it would be useful to set ourselves a numerical target, so that we can measure our progress towards it, and possibly bake it into our CI/CD pipeline at some point, so we don't regress. And to keep things SMART.

I am aware it's possible to treat compilation warnings about missing XML comments as errors, but that's not what I'm after. I don't want to require all public members to have comments just now (or, frankly, ever). I believe the same consideration rules out StyleCop.

kamilk
  • 3,829
  • 1
  • 27
  • 40
  • Look into GhostDoc, it writes the comments for you, and about 90% of the time, writes what you would have written yourself. There is a project setting to write the xml comments to a text file, which you could parse with some XSLT to give you the stats you want. – Neil Feb 09 '22 at 22:06
  • "myself and other recent joiners have complained" - my experience with coming in and complaining is a good way to end up leaving. I'd suggest you find a way to show that adding the comments is an asset to the project and not "tech debt that needs to be paid off". The existing devs usually don't like being told that their code sucks. – Enigmativity Feb 09 '22 at 22:09
  • 1
    Define easy, here's how you could get the comments programmatically https://learn.microsoft.com/en-us/archive/msdn-magazine/2019/october/csharp-accessing-xml-documentation-via-reflection. As for if this is easy, it's subjective. – funatparties Feb 09 '22 at 22:12
  • @Neil TBH, when I wrote that I don't want to impose that everything must have a comment, it's the memories of using GhostDoc that I had in mind. These generated comments add no information that can't be deduced from the method signature. You should only ever treat it as a starting point and always fill missing information in, but when the main motivation for adding a comment was to satisfy a StyleCop rule, that didn't tend to happen. – kamilk Feb 09 '22 at 22:23
  • 2
    @Enigmativity Thanks for pointing that out, I'll use more positive language when I talk to the team. I appreciate that it will require a diplomatic approach. When I said "complained", it's been mostly among us the recent joiners, we haven't been so vocal when talking to existing devs yet. – kamilk Feb 09 '22 at 22:34
  • To me, code comments are like varnish on wood. You can get by without it, but it'll look better with it. GhostDoc is like a machine varninsh, it's generally OK, but sometimes you need a hand varnished comment when the automatic one just isn't good enough. GhostDoc is also good at helping with badly named functions, if GD can't write proper English, your function is probably named badly too. – Neil Feb 11 '22 at 21:16
  • My way of looking at comments is that they are useful for explain any exogenous factors that impact your code, but otherwise clearly written code that is self-documenting is the gold standard. Comments can provide clarity, but now there is a maintenance and refactoring issue. Comments also are a source of bugs if the comment doesn't match the actual code. – Enigmativity Feb 11 '22 at 22:29

0 Answers0