DNN Development Tips:8 - Documenting your Code - To Comment or Not To Comment
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.