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?

marked as duplicate by GlenH7, Bart van Ingen Schenau, gnat, Dan Pichelman, Martijn Pieters Feb 20 '14 at 9:55

This question has been asked before and already has an answer. If those answers do not fully address your question, please ask a new question.

  • 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