Documentation and Comments

What’s a comment? A comment is a simple form of documentation. Documentation is text that you the programmer write to explain to someone else what your program is doing User manuals Prompts to the user during execution Design of the logic of the program A test plan for the program Comments inside the code of the program

Why do comments? You write comments to other people not to a computer All languages ignore comments – they are stripped from the code before the translator even sees them Who reads your code? These people also read your comments! Other team members if you are working on code as a team The programmer who gets the job of maintaining your code after you have left the company Yourself, maybe a week later, trying to remember why you did things that way Your TA while grading your program A comment is a chance to explain WHY you did this thing or that, not to explain HOW. The code itself tells how it was done.

How to do comments In Python there are two ways First way is to use a # (hash mark, number sign, pound sign) Everything you type to the right of the # sign to the end of that line is ignored by the interpreter For longer comments, you can use ‘’’ (that is 3 single quotes together) Once you’ve typed in ‘’’ you can enter as much text as you like, lines and paragraphs and whole pages. Everything is ignored until you enter another ‘’’

Where to do comments The Header comment (see Programming Standard page) Name, Section number Purpose of program Date completed Preconditions (inputs to program) Postconditions (outputs from program) Goes at the top of the source code of program assignments, good practice to put in lab assignment programs

Where to do comments (continued) Not every line of code needs a comment Write comments as though you were talking to a student in our class, i.e. they know some Python A comment like ctr = 0 # set variable to 0 is not helpful! A reader can tell what the code does Better would be ctr = 0 # initialize counter for lines If a comment gets long, put it on the line above the statement it’s about, rather than have to scroll the window back and forth