2 Votes
Comment on Comments & Naming
Nice article. Here is some of the tips I’ve picked up along the way…
- As someone who has been programming for 20+ years, I strongly disagree with Dr. Salih Yurtas. Ideally comments should be written BEFORE the code. Namely:
- Code tells you ‘HOW’ it is being done,
- Comments tell you ‘WHY’ it is being done. This is ESPECIALLY important for bug fixes to minimize the explicit side effects and ramifications.
- This prevents useless trivial comments such as: “x++; // inc x” while still allowing elegant or beautiful code.
- I have always maintained that if you can’t name something descriptively, chances are, you probably don’t understand the problem.
- Pick a naming convention
- Using the ‘verbNoun()’ function naming convention also minimizes confusion of what a function does.
- Using ‘On*()’ for "callbacks and pseudo-callbacks helps alert the reader when they are triggered.
- CamelCase for functions may also be helpful.
- Using an underscore ‘_’ in between function words is also an alternative.
- Using an underscore at the end of parameter names lets the caller know that it will be modified, instead of clumsy IN OUT clutter.
- Using an underscore in front of a variable lets programmers know that it is a private member variable.
- The most important thing: Pick one standard, and stick to it !
michael [AT] House Of Sas {dot} com
RE: Comment on Comments & Naming by jdkullmann
I too have been designing and writing software, now for over 36 years. I just wanted to point out for budding iPhone programmers out there that that last bullet item “underscore in front of a variable” should not be done when doing Mac or iPhone coding. Apple has reserved the leading underscore for their own use and unexpected overrides/name clashes because of it will be very hard to find.
Very nice article.
RE: Comment on Comments & Naming by Anonymous
Another thing to note on naming conventions, the so called “Hungarian Notation,” where the name is prefixed with a type. Far too may interpret this to mean the “actual type”. It is far more useful to use the “abstract type”.
Examples:
Actual type: unsigned int ui_PhaseCycles;
Abstract type: unsigned int counter_PhaseCycles;
While “ui_PhaseCycles” tells you that the variable is an unsigned integer, this is not truly helpful as it tells you nothing about how the variable is used. Also, if you need to change the type of the variable to, for example, signed long, you have to change every occurrence.
“counter_PhaseCycles” tells you that the variable is used for counting. This is much more useful during a code inspection or review. It allows one to see if, for example, the variable is being confused with a scaling factor.