Traditionally there are two schools of thought with comments.

• You need them because your code is way too clever and hard to read or understand.
• You don't need them because your code is self-documenting.

Some programming languages, e.g. C can be made very unreadable; if you indulge in write only code without comments, watch out because a few months down the line you will have forgotten what it did and if you need to change it...tough! That by the way is how I spent 8 hours over the recent holiday weekend. Amending code that I had not looked at since 1998! Thankfully it wasn't too bad. Not many comments though...

The 2nd school of thought says that as all code should be self documenting, you should always use sensible variable and function names. Whether you comment or not I couldn't agree more about the use of sensible names if the code has to be reused or maintained. Over the years I have written plenty of code using single or double letter variable names. But that was back when interpreters walked the earth (1980s) and long variable names were fractionally slower to parse than shorter ones. In fact some Basics back then only supported single or double letter variables. But we had Rem statements.

Despite the use of sensible names, there are times when you need to document other things that are indirectly applicable to your code. For example the ranges of allowed parameters, or "Don't call this until after you have called Y...". Nowadays you have no excuse about commenting and open source comment extractors like the open source documentation generator Doxygen (for C and C++ and other languages) or the C# /// make life so much easier. Doxygen is worthy of a place in the C Code library.

 

资料 学英文