[thelist] commenting code

[Steve Cook]

Finally a comment about comments that actually does have some importance! In
the project I'm working on we have discussed some commenting standards. We
have agreed for instance to comment the beginning of every sub / function

sub subPrintPage ' This subroutine will print out the page

... but we also comment very quickly the end of a subroutine with it's own
name, so that if it gets long it helps when browsing the code

end sub ' subPrintPage

We've also agreed on standards for the top of each script to help identify
what the script will do and for commenting functionality in hard to read
areas of code such as deeply nested loops, recursive functions etc.

We've also built standard naming conventions for variable names etc which
spread beyong just our code to image names, directory structures etc. It's
helpedour project no end, as we can confidently split up work between us and
know that we ca pick up someone else's code and easily work out what is
going on.

At the end of the day, you've got to ask yourself "Why am I using comments"
- if the answer is to make shared programming easier, or to remind you what
you were thinking when you return to your code, that will affect you choice
of comments accordingly. If the answer is that you want people to think how
cool you are when they read the source, you should probably become a sales
person instead!

.steve


----------------------------------
   WapWarp - http://wapwarp.com
 Wap-Dev - http://www.wap-dev.net
 Cookstour - http://cookstour.org
----------------------------------



> -----Original Message-----
> From: Michael McGlynn [mailto:blastronaut at excite.com]
> Sent: den 15 februari 2001 23:40
> To: thelist at lists.evolt.org
> Subject: [thelist] commenting code 
> 
> 
> Comments matter when you share pages. To establish a standard 
> in a workgroup
> is essential, and just good form for the casual coder. 
> 
> ¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤
> michael mcglynn
> interface designer
> www.blueripple.com
> ¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤¤
> 
>