Slide 1CommentsWhat Comments are NotTypes of CommentsTypes of CommentsTypes of CommentsTypes of CommentsTypes of CommentsTypes of CommentsThings to CommentMaintaining CommentsMaintaining CommentsMaintaining CommentsMaintaining CommentsMaintaining CommentsMaintaining CommentsMaintaining CommentsMaintaining CommentsMaintaining CommentsMore Commenting “DON’Ts”More Commenting “DON’Ts”More Commenting “DON’Ts”More Commenting “DON’Ts”More Commenting “DON’Ts”More Commenting “DON’Ts”More Commenting “DON’Ts”Commenting “DOs”Commenting “DOs”Commenting “DOs”Commenting “DOs”Commenting “DOs”Commenting “DOs”Other Commenting SuggestionsCommenting Control StructuresCommenting FunctionsCommunicating in Code:CommentingProgramming Studio, Fall 2017Tanzir AhmedNote: several examples in this lecture taken from The Practice of Programming by Kernighan and PikeCommentsAn internal documentation mechanismDocumentation of the code stays with and close to the codeComments should complement good coding style, not replace itThe better written your code, the fewer comments you will needPoor commenting is a waste of time and sometimes harmfulWhat Comments are NotDesign documentsAPI referencesSpecificationsPadding to increase your “lines of code”Places to tell jokes to future programmersTypes of CommentsRepeat of the CodeRepeating what code does or stating the obvious is useless//loop through all Teamsfor(i=0;i<NumTeams;i++) //add that team’s players to total TotalPlayers += Team[i].NumPlayers;Types of CommentsRepeat of the CodeRepeating what code does or stating the obvious is useless//Find total number of players in leaguefor(i=0;i<NumTeams;i++) TotalPlayers += Team[i].NumPlayers;Types of CommentsExplanation of the codeCan be a sign that the code is difficult to understandDon’t comment bad code – rewrite itIf the explanation is too long, code should be rewritten/* Update the attenuation due to multiple scattering whenever there is a valid layer hit. The next intersection layer hit will be skipped over and the intersection point will generate a new vector and the last vector created will be stored */for(i=IntersectLayer-1;i<NumLayersHit;i++) { if (isValidHit(r)) { Attenuation.Update(Layer[i++].HitPoint(genVector(r))); }}Types of CommentsMarker in the CodeUsed as notes to the developer//***** FIX THIS ROUTINEOften have key phrases to search onUsed to visually separat e code blocksAs a style element, e.g. function header blocksTypes of CommentsSummary of the codeShort statement summarizing several lines of code.Useful for quick scanning over code to find areas where things are happeningProvides a global “map” to the codeTypes of CommentsDescription of the code’s intentBest type – explains the why , not the howComments should add something that is not immediately evident from the codeUnderstanding the intent of code is usually the issue – it’s much easier to tell exactly what the code is doingThings to CommentFunctionsGlobal variablesCan be tough to keep track ofCode that is truly complicatedMight require lots of explanation, references to algorithmsMaintaining CommentsComments need to be maintained as code is edited!Conflicts between comments and code cause tremendous difficultyCommenting styles can assist with maintenance/*************************//* *//* My comments *//* *//*************************/Maintaining CommentsComments need to be maintained as code is edited!Conflicts between comments and code cause tremendous difficultyCommenting styles can assist with maintenance/************************* * * * My comments * * * *************************/Maintaining CommentsComments need to be maintained as code is edited!Conflicts between comments and code cause tremendous difficultyCommenting styles can assist with maintenance/************************ * * My comments * ************************/Maintaining CommentsComments need to be maintained as code is edited!Conflicts between comments and code cause tremendous difficultyCommenting styles can assist with maintenance/************************ My comments ************************/Maintaining CommentsComments need to be maintained as code is edited!Conflicts between comments and code cause tremendous difficultyCommenting styles can assist with maintenanceBlocks of commentsLining up commentsMaintaining CommentsDifficulty lining up comments:int Capacity; // Number of cats we could keepint NumCats; // Number of cats in the housefloat CatFood; // Monthly cost of cat foodMaintaining CommentsDifficulty lining up comments:int Capacity; // Number of cats we could keepint NumCats; // Number of cats in the housefloat CatFood; // Monthly cost of cat foodfloat BoardingCosts; // Cost to board cats per dayMaintaining CommentsDifficulty lining up comments:Difficult to maintain over time, so tend to degrade with modificationLeaving enough space often leads to short commentsMaintaining CommentsComments often lastDon’t use comments you don’t want others to seeDon’t expect comments to really be “temporary”Exceptions: temporary “markers”If markers are left in code, be sure they will be foundMore Commenting “DON’Ts”Don’t include useless commentsMOV AX, 723h ; R.I.P.L.V.BMore Commenting “DON’Ts”Don’t include useless commentsMOV AX, 723h ; R.I.P.L.V.B(Beethoven died in 1827 = 723h)More Commenting “DON’Ts”Don’t include useless commentsAvoid endline commentsFor one line of code, tend to be repetitive not much to say about one line of codeFor multiple lines of code, tend to be difficult to matchWhich lines does the comment “belong” to?Difficult to say too muchNot much roomMore Commenting “DON’Ts”Don’t include useless commentsAvoid endline commentsDon’t use too many commentsCan actually obscure the code itself!No set “ideal”, but one comment about every 10 lines or so is probably right.More Commenting “DON’Ts”Don’t include useless commentsAvoid endline commentsDon’t use too many