My opinion on inline comments is similar to my opinion on demolition charges; they're useful in exceedingly rare circumstances but if you use them all the time there's probably something wrong. Lots of inline comments do not maintainable code make. Their usage can generally be classified into the following categories:

  • Repeating what the code says. There's already something that says what the code does, it's called the code.
  • Repeating what the code used to do. If you work on a team where inline comments are regularly and consistently updated to match the code, congratulations because you're hallucinating.
  • Stating what the code should do but doesn't. May be useful when you find a bug and are trying to determine what the code is meant to do. More likely to be misleading.
  • Trying to be funny. There's a place for humour, and that place is the project schedule. Sure, it's dark humour and the jokes on you, but it's less likely to be seen by an end user with no sense of humour.
  • A large flashing warning that you need to refactor your code. If you need to keep explaining what you're doing your method is too long and has a poor name.
  • A subtle indication that the developer who added it thinks that his/her/its colleagues are morons. Often true, but such colleagues will ignore or misinterpret the comments anyway.
  • Explaining something genuinely non-obvious and in need to explanation. If you have more than a couple of comments like this in your codebase you're either doing something very complex or very very wrong.

As an example, I present my first Pascal assignment at university. I can't recall what it did, for it was trivial. I do recall getting full marks on it despite personally considering it to be an abomination. As the lecturer was big on comments I commented every single line, plus all the functions, data structures etc. This probably tripled the size of the code file. It added absolutely nothing to the readability of maintainability of the program. Indeed because it made it so much more verbose there it actually decreased the readability due to the sheer amount of trivial nonsense to wade through. This program would have been better with well names methods and variables and no comments at all.

The proper alternative to inline comments is readable code. In my arrogant opinion, you should do the following:

  • Don't put in trivial, redundant and obvious comments. Assume that the person reading the code can actually read the code.
  • Use meaningful names for types, methods, variables, fields etc. This gives useful information about the element everywhere it's used.
  • Extract code into methods. Combined with meaningful names (and some judicious pattern use) this allows you to read what the code is doing without having to worry about every detail at every point.
  • Put helpful comments (using the nifty XML commenting built into C#) onto types and their public elements. You can then automatically generate API documentation (I never actually do this, but you can).
  • Keep your logic as simple as possible (but no simpler). No one thinks you're clever when your overcomplicated solution turns out to have large numbers of bugs. Also bear in mind that localised complexity can result in overall simplicity if it removes redundancy. Think about the complexity as a whole. My standard pattern is to aim for the solution that results in the least code. Refactoring allows the addition of more sophisticated solutions as the total amount of code rises.
  • Write unit tests. Comments can be ignored, failing unit tests are much more noticeable (assuming they're run. Get a build server).