[cfaussie] Re: Code Commenting
2 things you should NOT do with commenting 1. state the obvious! cfset x = x _ 1 !--- increments the counter by one --- or my other fav !--- gets the data --- cfquery ... /cfquery 2. Comment out large blocks of code. For some reason when taught programming everyone gets the idea you should always comment out code and not delete it. This is not 100% true. If you have version control, then just delete it! Its seriously frustrating trying to figure out why something was removed from the codebase. It also makes things harder, since not only are you are trying to work out what the code DOES do, but also why it DOESNT do somehting else. At the very least, put a comment inside the block to say why it was removed eg. !--- 2007/07/29, pat: removed this block beause xyz requirement changed --- ... my 1c+1c Pat On Jul 28, 9:04 pm, Barry Beattie [EMAIL PROTECTED] wrote: (pls forgive, gotta be quick) there's the other parts to it as well, header info on the code files explaining date, purpose, revision number, bug fixes, etc. Some people build that into their source code control as automated/fill out the form commits, etc. then there's back to basics old fashioned CompSci data dictionaries, etc, explaining every variable used, datatype, initialisation value, range/out of bounds, etc. but the biggest thing of all is the ability to track changes, both with sensible using of source control and comments within the code explaining what was changed and why. the thing to keep in mind always is maintainability in the future. if memory and guesswork (naming format of variables) is the only thing left after code is committed then it's failed. I've got a bloated access database I'm having to migrate data out of right this minute. I'm thinking of all sorts of nasty names to the people that wrote and maintained it... my 2c. back to this shocker mdb file... b On 7/28/07, M@ Bourke [EMAIL PROTECTED] wrote: the thought that the code should be self-explanatory everyone likes to think there code is self explanatory lol. although it should be as self documenting as possible, you can comment so the user doesn't have to view the whole code, like at the top of the page give it a little description and also include its dependencies also if ya got some massive big loop then a one line comment at the top can be easier for the person to read then 100 lines of self explanatory code. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups cfaussie group. To post to this group, send email to cfaussie@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/cfaussie?hl=en -~--~~~~--~~--~--~---
[cfaussie] Re: Code Commenting
the thought that the code should be self-explanatory everyone likes to think there code is self explanatory lol. although it should be as self documenting as possible, you can comment so the user doesn't have to view the whole code, like at the top of the page give it a little description and also include its dependencies also if ya got some massive big loop then a one line comment at the top can be easier for the person to read then 100 lines of self explanatory code. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups cfaussie group. To post to this group, send email to cfaussie@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/cfaussie?hl=en -~--~~~~--~~--~--~---
[cfaussie] Re: Code Commenting
(pls forgive, gotta be quick) there's the other parts to it as well, header info on the code files explaining date, purpose, revision number, bug fixes, etc. Some people build that into their source code control as automated/fill out the form commits, etc. then there's back to basics old fashioned CompSci data dictionaries, etc, explaining every variable used, datatype, initialisation value, range/out of bounds, etc. but the biggest thing of all is the ability to track changes, both with sensible using of source control and comments within the code explaining what was changed and why. the thing to keep in mind always is maintainability in the future. if memory and guesswork (naming format of variables) is the only thing left after code is committed then it's failed. I've got a bloated access database I'm having to migrate data out of right this minute. I'm thinking of all sorts of nasty names to the people that wrote and maintained it... my 2c. back to this shocker mdb file... b On 7/28/07, M@ Bourke [EMAIL PROTECTED] wrote: the thought that the code should be self-explanatory everyone likes to think there code is self explanatory lol. although it should be as self documenting as possible, you can comment so the user doesn't have to view the whole code, like at the top of the page give it a little description and also include its dependencies also if ya got some massive big loop then a one line comment at the top can be easier for the person to read then 100 lines of self explanatory code. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups cfaussie group. To post to this group, send email to cfaussie@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/cfaussie?hl=en -~--~~~~--~~--~--~---
