I've recently realised that my workplace doesn't comment their ASP.NET MVC applications. By 'doesn't document', I mean there is probably 1 line of comment per model/view/controller. No file purpose, date created etc. The excuse is that the MVC should be self documenting, with skinny controllers, self-documenting view code etc. This is a fine explanation, but several things affect this statement:

  • Javascript technologies are also being implemented alongside the view code with no documentation as to their integration (the javascript code is also undocumented)
  • There are multiple databases and providers serving internal and external content (undocumented)
  • There is regular confusion daily amongst the programmers of what exactly is going on in any particular module. THis takes about 3-4 minutes of a co-worker's time to clear up.

Is this commenting practice lazy and bound to cause more problems than it's worth? Or am I just not adept enough at reading self-documenting code? As a side question, should MVC applications be less rigid in their commenting standards since the separation of concerns should make code obvious?

  • 2
    Some comments (date created for instance) serve little purpose in my opinion. Version control covers that. The length of a comment isn't what makes it a good comment. If its clear and concise its better than a multi paragraph comment be leagues. If the code requires lengthy comments then someone might want to evaluate the names and functionality of a given class with few exceptions for complex business logic.
    – Rig
    Feb 3 '14 at 3:22
  • 1
  • It rather depends on who is looking at the code. For novice programmers, there can't be enough comments. For seasoned ones, there are probably too many.
    – Robbie Dee
    Feb 3 '14 at 10:13