<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<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 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;}
@font-face
{font-family:Consolas;
panose-1:2 11 6 9 2 2 4 3 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;}
p
{mso-style-priority:99;
mso-margin-top-alt:auto;
margin-right:0cm;
mso-margin-bottom-alt:auto;
margin-left:0cm;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
p.MsoAcetate, li.MsoAcetate, div.MsoAcetate
{mso-style-priority:99;
mso-style-link:"Balloon Text Char";
margin:0cm;
margin-bottom:.0001pt;
font-size:8.0pt;
font-family:"Tahoma","sans-serif";
mso-fareast-language:EN-US;}
span.EmailStyle18
{mso-style-type:personal;
font-family:"Calibri","sans-serif";
color:windowtext;}
span.EmailStyle19
{mso-style-type:personal;
font-family:"Calibri","sans-serif";
color:#1F497D;}
span.EmailStyle20
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
span.BalloonTextChar
{mso-style-name:"Balloon Text Char";
mso-style-priority:99;
mso-style-link:"Balloon Text";
font-family:"Tahoma","sans-serif";
mso-fareast-language:EN-US;}
.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'>Chris,<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'>Very very nice!! I will definitely make use of this.<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'>Adrian Janson<o:p></o:p></span></p><p class=MsoNormal><span style='color:#1F497D'><o:p> </o:p></span></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>Bucknell, Chris<br><b>Sent:</b> Friday, 4 May 2012 10:18 AM<br><b>To:</b> Year 12 Software Development Teachers' Mailing List<br><b>Subject:</b> Re: [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><span style='color:#1F497D'>I came across a M$ document a while ago Called “All-In-One Code Framework Coding Standards” which is for all .Net languages. I use an edited version (below) of this for my class when coding in VB to describe how to comment and layout their code.</span><o:p></o:p></p><p class=MsoNormal><span style='color:#1F497D'> </span><o:p></o:p></p><p class=MsoNormal><span style='color:#1F497D'>Hope this is of use</span><o:p></o:p></p><p class=MsoNormal><span style='color:#1F497D'> </span><o:p></o:p></p><p class=MsoNormal><span style='color:#1F497D'>Regards Chris</span><o:p></o:p></p><div style='border:none;border-bottom:double windowtext 2.25pt;padding:0cm 0cm 1.0pt 0cm'><p class=MsoNormal><span style='color:#1F497D'> </span><o:p></o:p></p></div><p class=MsoNormal><span style='color:#1F497D'> </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:7.0pt;margin-left:0cm'><b><span lang=EN-US style='font-size:16.0pt;font-family:"Calibri","sans-serif";color:#17365D'>Pro-Comment Point #1: It's important to communicate what the code SHOULD be doing</span></b><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:7.0pt;margin-left:0cm'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>Source code must follow the syntactic tenants of the computer language. While language designers make significant efforts to define a readable syntax, at its core the language syntax exists for the compiler or interpreter and not the developer. Thus, comments are required to communicate the intent of the source apart from its functionality. When reading source code, it is extremely difficult to be absolutely certain of what the code is doing, as well to be certain as to what the original author intended. Comments should clearly communicate the developer's intent and if needed, an explanation as to how the source code algorithm accomplishes that intent.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:7.0pt;margin-left:0cm'><b><span lang=EN-US style='font-size:16.0pt;font-family:"Calibri","sans-serif";color:#17365D'>Pro-Comment Point #2: Comments show respect for the next developer to read your code</span></b><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:7.0pt;margin-left:0cm'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>The Golden Rule applies in source code as well; do unto the next developer as you would have them do unto you. Source code should be written in the way that you yourself would most like to encounter unfamiliar code. It should be well-structured with a clear logic flow, and be both efficient and effective. Comments enhance the readability of the code, so that its intent and approach are immediately apparent with a clean appearance.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:7.0pt;margin-left:0cm'><b><span lang=EN-US style='font-size:16.0pt;font-family:"Calibri","sans-serif";color:#17365D'>Pro-Comment Point #3: Comments indicate potential problem areas to avoid</span></b><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:7.0pt;margin-left:0cm'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>Comments should mention factors that may be of concern for the developer or tester. Boundary conditions, valid argument ranges, and corner cases are all important factors to mention in comments for the benefit of future developers and testers.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='mso-margin-top-alt:12.0pt;margin-right:0cm;margin-bottom:0cm;margin-left:0cm;margin-bottom:.0001pt'><b><span lang=EN-US style='font-size:16.0pt;font-family:"Calibri","sans-serif";color:#17365D'>1. Whitespace</span></b><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><b><span lang=EN-US style='font-size:13.0pt;font-family:"Calibri","sans-serif";color:#366092'>1.1 Blank Lines</span></b><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should </span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>use blank lines to separate groups of related statements. Omit extra blank lines that do not make the code easier to read. For example, you can have a blank line between variable declarations and code.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:Consolas;color:#00B050'>Good:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:blue'>Sub</span><span style='font-size:9.0pt;font-family:Consolas'> ProcessItem(<span style='color:blue'>ByVal</span> item <span style='color:blue'>As</span> <span style='color:blue'>String</span>)</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Dim</span> counter <span style='color:blue'>As</span> <span style='color:blue'>Integer</span> = 0</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Dim</span> flag <span style='color:blue'>As</span> <span style='color:blue'>Boolean</span> = <span style='color:blue'>True</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>If</span> flag <span style='color:blue'>Then</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:green'>'Do something</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>End</span> <span style='color:blue'>If</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:blue'>End</span><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Sub</span></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:10.0pt;margin-left:0cm'><span style='font-size:9.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:red'>Bad:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:blue'>Sub</span><span style='font-size:9.0pt;font-family:Consolas'> ProcessItem(<span style='color:blue'>ByVal</span> item <span style='color:blue'>As</span> <span style='color:blue'>String</span>)</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Dim</span> counter <span style='color:blue'>As</span> <span style='color:blue'>Integer</span> = 0</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Dim</span> flag <span style='color:blue'>As</span> <span style='color:blue'>Boolean</span> = <span style='color:blue'>True</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>If</span> flag <span style='color:blue'>Then</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:green'>'Do something</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>End</span> <span style='color:blue'>If</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:blue'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:blue'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:blue'>End</span><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Sub</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>In this example of bad usage of blank lines, there are multiple blank lines between the local variable declarations, and multiple blank likes after the ‘if’ block.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should</span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> use two blank lines to separate method implementations and class declarations.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><b><span lang=EN-US style='font-size:13.0pt;font-family:"Calibri","sans-serif";color:#366092'>1.2 Spaces</span></b><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>Spaces improve readability by decreasing code density. Here are some guidelines for the use of space characters within code: </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should<i> </i></span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>use spaces within a line as follows.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'>Good:</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'>CreateFoo() <span style='color:green'>' No space between function name and parenthesis</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'>Method(myChar, 0, 1) <span style='color:green'>' Single space after a comma</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'>x = array(index) <span style='color:green'>' No spaces inside brackets</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:blue'>While</span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'> (x = y) <span style='color:green'>' Single space before flow control statements</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:blue'>If</span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'> (x = y) <span style='color:blue'>Then </span><span style='color:green'>' Single space separates operators</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:red'>Bad:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'>CreateFoo () <span style='color:green'>' Space between function name and parenthesis</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'>Method(myChar,0,1) <span style='color:green'>' No spaces after commas</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'>CreateFoo( myChar, 0, 1 ) <span style='color:green'>' Space before first arg, after last arg</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'>x = array( index ) <span style='color:green'>' Spaces inside brackets</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:blue'>While</span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'>(x = y) <span style='color:green'>' No space before flow control statements</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:blue'>If</span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'> (x=y) <span style='color:blue'>Then </span><span style='color:green'>' No space separates operators</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><b><span lang=EN-US style='font-size:16.0pt;font-family:"Calibri","sans-serif";color:#17365D'>2. Comments</span></b><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should</span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> use comments that summarize what a piece of code is designed to do and why. <b>Do not</b> use comments to repeat the code.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'>Good:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' Determine whether system is running Windows Vista or later operating </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' systems (major version >= 6) because they support linked tokens, but </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' previous versions (major version < 6) do not.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:red'>Bad:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' The following code sets the variable i to the starting value of the </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' array. Then it loops through each item in the array.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should</span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> use single-line syntax (' …) is preferred even when a comment spans multiple lines.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'>Good:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' Get and display the process elevation information (IsProcessElevated) </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' and integrity level (GetProcessIntegrityLevel). The information is not </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' available on operating systems prior to Windows Vista.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:blue'>If</span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'> (Environment.OSVersion.Version.Major >= 6) <span style='color:blue'>Then</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:blue'>End</span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'> <span style='color:blue'>If</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should</span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> indent comments at the same level as the code they describe.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should</span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> use full sentences with initial caps, a terminating period and proper punctuation and spelling in comments.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'>Good:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'Initialize the components on the Windows Form.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'>InitializeComponent()</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:red'>Bad:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'initialize the components on the Windows Form</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'>InitializeComponent()</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><b><span style='font-size:13.0pt;font-family:"Calibri","sans-serif";color:#366092'>2.1 </span></b><b><span lang=EN-US style='font-size:13.0pt;font-family:"Calibri","sans-serif";color:#366092'>Inline Code Comments</span></b><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>Inline comments should be included on their own line and should be indented at the same level as the code they are commenting on, with a blank line before, but none after. Comments describing a block of code should appear on a line by themselves, indented as the code they describe, with one blank line before it and one blank line after it. For example:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:blue'>If</span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'> MAXVAL >= exampleLength <span style='color:blue'>Then</span><br> <span style='color:green'>' Reprort the error.<br></span> ReportError(GetLastError())</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'> ' The value is out of range, we cannot continue.</span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'><br> <span style='color:blue'>Return</span> E_INVALIDARG<br><span style='color:blue'>End If</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>Inline comments are permissible on the same line as the actual code only when giving a brief description of a structure member, class member variable, parameter, or a short statement. In this case it is a good idea to align the comments for all variables. For example:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Dim</span> MAX_STUDENTS <span style='color:blue'>As</span> <span style='color:blue'>Integer</span> = 20</span><span style='font-size:9.0pt;font-family:"Courier New"'> </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'The maximum number of students allowed</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Do</span> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'> ...</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Loop While</span> <span style='color:blue'>Not </span>finished</span><span style='font-size:9.0pt;font-family:"Courier New"'> </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'Continue if not finished</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:red'>ý</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:red'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should not</span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> drown your code in comments. Commenting every line with obvious descriptions of what the code does actually hinders readability and comprehension. Single-line comments should be used when the code is doing something that might not be immediately obvious.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>The following example contains many unnecessary comments:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:red'>Bad:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:green'>'Loop through each item in the student array</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:blue'>For</span><span style='font-size:9.0pt;font-family:Consolas'> i <span style='color:blue'>As</span> <span style='color:blue'>Integer</span> = 1 <span style='color:blue'>To</span> MAX_STUDENTS</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Dim</span> stud <span style='color:blue'>As</span> <span style='color:blue'>String</span> = students(i) <span style='color:green'>'Get the next student</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>If</span> Left(stud, 1) = <span style='color:#A31515'>"a"</span> <span style='color:blue'>And</span> stud.Length > longestName <span style='color:blue'>Then</span> <span style='color:green'>'Process if it's a name starting with "a" and its the longest</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> longestName = stud.Length <span style='color:green'>'Save the length as the longest</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> biggestName = stud <span style='color:green'>'Remember the student as well</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>End</span> <span style='color:blue'>If</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:blue'>Next</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'>Good:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' Loop through each item in the </span><span style='font-size:9.0pt;font-family:Consolas;color:green'>student </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>array, find the </span><span style='font-size:9.0pt;font-family:Consolas;color:green'>student </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>with </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' the longest "A" name, and store it in ‘biggestName’.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:blue'>For</span><span style='font-size:9.0pt;font-family:Consolas'> i <span style='color:blue'>As</span> <span style='color:blue'>Integer</span> = 1 <span style='color:blue'>To</span> MAX_STUDENTS</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>Dim</span> stud <span style='color:blue'>As</span> <span style='color:blue'>String</span> = students(i) </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>If</span> Left(stud, 1) = <span style='color:#A31515'>"a"</span> <span style='color:blue'>And</span> stud.Length > longestName <span style='color:blue'>Then</span> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> longestName = stud.Length </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> biggestName = stud</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas'> <span style='color:blue'>End</span> <span style='color:blue'>If</span></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:9.0pt;font-family:Consolas;color:blue'>Next</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should</span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> add comments to call out non-intuitive or behavior that is not obvious from reading the code.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:13.0pt;font-family:"Calibri","sans-serif";color:#366092'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><b><span style='font-size:13.0pt;font-family:"Calibri","sans-serif";color:#366092'>2.2 File Header Comments</span></b><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>Do</span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> have a file header comment at the start of every human-created code file. The header comment templates are as follows:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>VB.NET file header comment template:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'***************************** Module Header *******************************</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' Module Name: <File Name></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' Project: <Sample Name></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' Copyright (c) Microsoft Corporation.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' <Description of the file></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' This source is subject to the Microsoft Public License.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' See <a href="http://www.microsoft.com/opensource/licenses.mspx#Ms-PL">http://www.microsoft.com/opensource/licenses.mspx#Ms-PL</a>.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' All other rights reserved.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'***************************************************************************</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>For example, </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'****************************** Module Header ******************************</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'Module Name: CppUACSelfElevation.cpp</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'Project: CppUACSelfElevation</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'Copyright (c) Microsoft Corporation.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'User Account Control (UAC) is a new security component in Windows Vista and </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'newer operating systems. With UAC fully enabled, interactive administrators </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'normally run with least user privileges. This example demonstrates how to </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'check the privilege level of the current process, and how to self-elevate </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'the process by giving explicit consent with the Consent UI. </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'This source is subject to the Microsoft Public License.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'See <a href="http://www.microsoft.com/opensource/licenses.mspx#Ms-PL">http://www.microsoft.com/opensource/licenses.mspx#Ms-PL</a>.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'All other rights reserved.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>' </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.</span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>'***************************************************************************</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><b><span style='font-size:13.0pt;font-family:"Calibri","sans-serif";color:#366092'>2.3 Class Comments</span></b><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should<i> </i></span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>provide banner comments for all classes and structures that are non-trivial. The level of commenting should be appropriate based on the audience of the code. </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>VB.NET class comment template:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'><summary></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' <Class description></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'></summary></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><b><span style='font-size:13.0pt;font-family:"Calibri","sans-serif";color:#366092'>2.4 Function Comments</span></b><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;color:#00B050'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:#00B050'>þ</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:#00B050'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>You should<i> </i></span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>provide banner comments for all public and non-public functions that are not trivial. The level of commenting should be appropriate based on the audience of the code. </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>VB.NET function comment template:</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'><summary></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' <Function description></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'></summary></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'><param name="Parameter name"></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' <Parameter description></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'></param></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'><returns></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' <Description of function return value></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'></returns></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'><exception cref="<Exception type>"></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' <Exception that may be thrown by the function></span><o:p></o:p></p><p style='mso-margin-top-alt:0cm;margin-right:0cm;margin-bottom:0cm;margin-left:27.0pt;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'></exception></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>For example, </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'><summary></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' The function checks whether the primary access token of the process </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' belongs to user account that is a member of the local Administrators </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' group, even if it currently is not elevated.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'></summary></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'><param name="token"></span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>The handle to an access token</span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'></param></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'><returns></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' Returns true if the primary access token of the process belongs to </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' user account that is a member of the local Administrators group. </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' Returns false if the token does not.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'></returns></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'><exception cref="System.ComponentModel.Win32Exception"></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' When any native Windows API call fails, the function throws a </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' Win32Exception with the last error code.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:green'>''' </span><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:gray'></exception></span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>Any method or function which can fail with side-effects should have those side-effects clearly communicated in the function comment. As a general rule, code should be written so that it has no side-effects in error or failure cases; the presence of such side-effects should have some clear justification when the code is written. (Such justification is not necessary for routines which zero-out or otherwise overwrite some output-only parameter.)</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><b><span style='font-size:13.0pt;font-family:"Calibri","sans-serif";color:#366092'>2.5 TODO Comments</span></b><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:13.0pt;font-family:"Calibri","sans-serif";color:#366092'> </span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span lang=EN-US style='font-size:11.0pt;font-family:Wingdings;color:red'>ý</span><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif";color:red'> </span><b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'>Do not</span></b><span lang=EN-US style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> use TODO comments in any released samples. Every sample must be complete and not require a list of unfinished tasks sprinkled throughout the code.</span><o:p></o:p></p><p style='margin:0cm;margin-bottom:.0001pt'><span style='font-size:11.0pt;font-family:"Calibri","sans-serif"'> </span><o:p></o:p></p><p class=MsoNormal><span style='color:#1F497D'> </span><o:p></o:p></p><p class=MsoNormal><span style='color:#1F497D'> </span><o:p></o:p></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'> <a href="mailto:sofdev-bounces@edulists.com.au">sofdev-bounces@edulists.com.au</a> <a href="mailto:[mailto:sofdev-bounces@edulists.com.au]">[mailto:sofdev-bounces@edulists.com.au]</a> <b>On Behalf Of </b>Ben Hines<br><b>Sent:</b> Friday, 4 May 2012 9:34 AM<br><b>To:</b> <a href="mailto:sofdev@edulists.com.au">sofdev@edulists.com.au</a><br><b>Subject:</b> [Year 12 SofDev] Query about Internal Documentation</span><o:p></o:p></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><o:p></o:p></p><p class=MsoNormal><span style='color:#1F497D;mso-fareast-language:EN-AU'> </span><o:p></o:p></p><p class=MsoNormal><i><span style='color:#1F497D;mso-fareast-language:EN-AU'>VCE Maths/ICT Teacher</span></i><o:p></o:p></p><p class=MsoNormal><i><span style='color:#1F497D;mso-fareast-language:EN-AU'>Senior School Campus - Christian College Geelong</span></i><o:p></o:p></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)</span><o:p></o:p></p><p class=MsoNormal> <o:p></o:p></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.</span><o:p></o:p></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> </span><o:p></o:p></p></div><p></p><p><b>Important - </b>This email and any attachments may be confidential. If received in error, please contact us and delete all copies. Before opening or using attachments check them for viruses and defects. Regardless of any loss, damage or consequence, whether caused by the negligence of the sender or not, resulting directly or indirectly from the use of any attached files our liability is limited to resupplying any affected attachments. Any representations or opinions expressed are those of the individual sender, and not necessarily those of the Department of Education and Early Childhood Development.</p>
</body></html>