Thoughts from the Wet Coast

The musings of an ASP.NET Developer from Canada's We(s)t Coast

DNN Development Tips:8 - Documenting your Code - To Comment or Not To Comment

Last Modified: May 2 2017
Oct 21 2014

This DNN Development Tip is a short one – but an important one.

There is a facebook meme that has been doing the rounds recently that amongst other things talks about good versus bad commenting of code.  It goes something like this.

Comments in my code – Helpful documentation

Comments in someone else’s code – Poor code design

The basic principle of the latter statement is that code should be self-documenting – for the most part.  It is a Best Practice to give meaningful names to all methods, parameters and variables.  Well designed code should not need comments to help a reader understand what is going on – it should be self-evident.

Now this is not always possible to achieve, especially with some complex algorithms– and so there are exceptions to this rule, but for the most part excessive use of comments implies that the code is not well designed/written.

So if your code needs a lot of comments then maybe you haven’t designed it very well.

Disclaimer

The opinions expressed herein are my own personal opinions and do not represent my employer's view in anyway.

Categories

Tags