Isn't commenting your code also a proven practice?

Jul 7, 2010 at 5:38 PM
This example code and documentation were entended to teach others, correct? It seems to be a common trend in the programming community, any code or sample application that are available to the community for free as a learning resource typically never have but a few if any at all, inline comments to help one follow along with what is being taught. On the other hand, it has been my experience over the years that in a work environment where one is writing code in exchange for compensation and employment benefits inline comments are typically required, or atleast mandated by your fellow developers as an effort to document your code for others as well as yourself. Is it too much to ask a professional software engineer to stop assuming your code reads like a book and utilize a basic concept taught in "Intro to Programming" called inline comments, which is also a form of documentation. I think the P&P stuff would be alot more useful if the code was also commented.
Jul 15, 2010 at 5:37 PM
Edited Jul 15, 2010 at 5:39 PM

Hi,

Thanks for your feedback. It is useful, as the assets are meant to be used as guidance among other purposes. I will notify the product team about this. It would be helpful if you could answer this questions:

  • What asset are you using?
  • What part of this asset do you consider requires comments to be better understood? As you know, having a lot of code comments in the code is often a signal of unclear code, as it needs to be constantly explained.

On the other hand, in the latest p&p Client assets, such as the Web Client Developer Guidance or Prism the product team is more focused on self documenting code.

Take into account, that many of the parts you find unclear in the source code, might be explained with more detail in the documentation, Quickstarts or Reference Implementation of the asset you are using. Also consider, that Unit Tests can be used to better understand pieces of code, as they are the most clear expressions of what the code should do. 

Please let me know if this helps.

Fernando Antivero
http://blogs.southworks.net/fantivero