Code Commenting in Context
There are a huge number of articles on the web about "How to Comment Your Code" or "10 Top Tips to Comment Your Code". Having read a number of these I noticed the apparent absence of context in the advice given. Without a context it is easy to argue that one approach is better than another. Some people will argue that "all code should be commented", others that "if you write good code you don't need to comment". Both statements have value but without a context neither is right or wrong. In this post I'm going to discuss a number of approaches and suggest in what situation an approach is most suitable.
Comment everything
If you've ever used the Microsoft .NET Framework Class Library then you're most probably familiar with the MSDN style of documentation. You too can easily achieve this style of documentation, for your software, by commenting everything in your code and pointing a documentation tool (e.g. Sandcastle) at your assembly. If that's your goal then this is a suitable approach, but it has plenty of negatives; You'll find yourself commenting the down right obvious; The amount of time it takes to write "code" will increase; Your files will naturally get bigger; You'll go mad; The list goes on. If automated documentation isn't your goal DON'T comment everything.
Don't comment anything
Some developers believe it’s not necessary to comment your code because your code should be “self documenting”. Perhaps these people don’t like to write comments or have only ever worked on simple systems. Striving to write simple code, which would indeed be “self documenting”, should always be high on a developer’s list of priorities, but there will be many occasions when you need to comment why you are doing something. The question of why is usually simply an explanation of what the code is required to do.
Comment everything
If you've ever used the Microsoft .NET Framework Class Library then you're most probably familiar with the MSDN style of documentation. You too can easily achieve this style of documentation, for your software, by commenting everything in your code and pointing a documentation tool (e.g. Sandcastle) at your assembly. If that's your goal then this is a suitable approach, but it has plenty of negatives; You'll find yourself commenting the down right obvious; The amount of time it takes to write "code" will increase; Your files will naturally get bigger; You'll go mad; The list goes on. If automated documentation isn't your goal DON'T comment everything.
Don't comment anything
Some developers believe it’s not necessary to comment your code because your code should be “self documenting”. Perhaps these people don’t like to write comments or have only ever worked on simple systems. Striving to write simple code, which would indeed be “self documenting”, should always be high on a developer’s list of priorities, but there will be many occasions when you need to comment why you are doing something. The question of why is usually simply an explanation of what the code is required to do.
Comments
Post a Comment