<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40"><head><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii"><meta name=Generator content="Microsoft Word 14 (filtered medium)"><!--[if !mso]><style>v\:* {behavior:url(#default#VML);}
o\:* {behavior:url(#default#VML);}
w\:* {behavior:url(#default#VML);}
shape {behavior:url(#default#VML);}
</style><![endif]--><style><!--
/* Font Definitions */
@font-face
{font-family:Wingdings;
panose-1:5 0 0 0 0 0 0 0 0 0;}
@font-face
{font-family:Wingdings;
panose-1:5 0 0 0 0 0 0 0 0 0;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:Tahoma;
panose-1:2 11 6 4 3 5 4 4 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0cm;
margin-bottom:.0001pt;
font-size:11.0pt;
font-family:"Calibri","sans-serif";
mso-fareast-language:EN-US;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.EmailStyle17
{mso-style-type:personal;
font-family:"Calibri","sans-serif";
color:windowtext;}
span.EmailStyle18
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:612.0pt 792.0pt;
margin:72.0pt 72.0pt 72.0pt 72.0pt;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]--></head><body lang=EN-AU link=blue vlink=purple><div class=WordSection1><p class=MsoNormal><span style='color:#1F497D'>I make my kids live by this mantra: "Don't include a single line in your code which you could not explain to your grandmother in a matter of two minutes."<o:p></o:p></span></p><p class=MsoNormal><span style='color:#1F497D'><o:p> </o:p></span></p><p class=MsoNormal><span style='color:#1F497D'>I’m not sure of any set rules for internal documentation, just a sensible explanation of what the code is doing in that particular spot.<o:p></o:p></span></p><p class=MsoNormal><span style='color:#1F497D'><o:p> </o:p></span></p><p class=MsoNormal><span style='color:#1F497D'>Cheers<o:p></o:p></span></p><p class=MsoNormal><span style='color:#1F497D'><o:p> </o:p></span></p><p class=MsoNormal><span style='color:#1F497D'>Trav<o:p></o:p></span></p><p class=MsoNormal><span style='color:#1F497D'><o:p> </o:p></span></p><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal><span style='color:#1F497D'><o:p> </o:p></span></p><p class=MsoNormal><a name="_MailEndCompose"><span style='color:#1F497D'><o:p> </o:p></span></a></p><div><div style='border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0cm 0cm 0cm'><p class=MsoNormal><b><span lang=EN-US style='font-size:10.0pt;font-family:"Tahoma","sans-serif";mso-fareast-language:EN-AU'>From:</span></b><span lang=EN-US style='font-size:10.0pt;font-family:"Tahoma","sans-serif";mso-fareast-language:EN-AU'> sofdev-bounces@edulists.com.au [mailto:sofdev-bounces@edulists.com.au] <b>On Behalf Of </b>Ben Hines<br><b>Sent:</b> Friday, 4 May 2012 9:34 AM<br><b>To:</b> sofdev@edulists.com.au<br><b>Subject:</b> [Year 12 SofDev] Query about Internal Documentation<o:p></o:p></span></p></div></div><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal>Hey List!<o:p></o:p></p><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal>Just wondering what the standards/conventions are for internal documentation (Comments). Are there any or do we just teach our students to sensibly comment sections of code with a little explanation of what the code is achieving. The main thing I learnt at uni was when commenting don’t go too overboard with explanations…<o:p></o:p></p><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal>Any ideas? <o:p></o:p></p><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal><b><span style='color:#1F497D;mso-fareast-language:EN-AU'>Mr Ben Hines</span></b><b><span style='font-size:12.0pt;color:#1F497D;mso-fareast-language:EN-AU'><o:p></o:p></span></b></p><p class=MsoNormal><span style='color:#1F497D;mso-fareast-language:EN-AU'><o:p> </o:p></span></p><p class=MsoNormal><i><span style='color:#1F497D;mso-fareast-language:EN-AU'>VCE Maths/ICT Teacher<o:p></o:p></span></i></p><p class=MsoNormal><i><span style='color:#1F497D;mso-fareast-language:EN-AU'>Senior School Campus - Christian College Geelong<o:p></o:p></span></i></p><p class=MsoNormal><span style='font-family:Wingdings;color:#1F497D;mso-fareast-language:EN-AU'>(</span><span style='color:#1F497D;mso-fareast-language:EN-AU'>(03) 52411577 (ext. 180)<o:p></o:p></span></p><p class=MsoNormal><o:p> </o:p></p><p class=MsoNormal><span style='font-size:12.0pt;font-family:"Times New Roman","serif";mso-fareast-language:EN-AU'><br><br>Scanned by the Netbox from <a href="http://netboxblue.com/">Netbox Blue</a> <o:p></o:p></span></p><p class=MsoNormal style='margin-bottom:12.0pt'><span style='font-size:12.0pt;font-family:"Times New Roman","serif";mso-fareast-language:EN-AU'><br>This e-mail is intended for the use of the named individual or entity and may contain confidential and privileged information. Any dissemination, distribution or copying by anyone other than the intended recipient of this e-mail is strictly prohibited. If this e-mail has been received in error, then please notify Christian College or the author of this email immediately and destroy the original message. We have made every attempt to ensure this e-mail message is free from computer viruses however the attached files are provided on the basis that the user assumes all responsibility for use of the material transmitted. Views, opinions, etc. expressed reflect those of the author and not Christian College nor its associated companies and campuses which includes Eden Quality Services Pty Ltd.<o:p></o:p></span></p><div class=MsoNormal align=center style='text-align:center'><span style='font-size:12.0pt;font-family:"Times New Roman","serif";mso-fareast-language:EN-AU'><hr size=1 width="100%" align=center></span></div><p class=MsoNormal><span style='font-size:12.0pt;font-family:"Times New Roman","serif";mso-fareast-language:EN-AU'>Message protected by MailGuard: e-mail anti-virus, anti-spam and content filtering.<br><a href="http://www.mailguard.com.au">http://www.mailguard.com.au</a><br> <br> <o:p></o:p></span></p></div></body></html>