[[Outcome 1 - Programming#11. purposes of internal documentation, including|U3 - AOS1 - KK11]] ## What does this code do? You have 10 seconds… ![[image-37.png]] Not too hard but definitely not easy to figure out in 10 seconds. What is missing from this? ## What about now? ![[image-38.png]] ## Internal documentation conventions A header comment, containing the name of the file, a brief description of the program, the author's name, and the date the program was first created. Documentation strings for classes and methods, describing their behaviour of the program, the author's name, and the date the program was first created. Function comments, describing their purpose, as well as describing all inputs and outputs and their respective date. ## Explanation ![[image-39.png]] Examples include: • The purpose of a module • Constraints (i.e. changing this would move a GUI element to the wrong place) • External libraries required by the module/code ## Maintenance ![[image-40.png]] Information such as creator’s identity, date of creation, last modification, version number & assumptions (e.g. operating system, hardware, that certain files already exist and are in a given format). • Problems that need to be fixed • You might outlined previous fixes (for example perhaps you are using an outdated library as the newer version is incompatible etc.) ## Planning Outlining were code is missing or functionality needs to be added ## Meaningful comments  VCAA requires that you be assessed on the meaningfulness of your comments. What does that mean? It means adding useful information that is not already evident in the code. For example: ![[image-41.png]] Versus something obvious like ![[image-43.png]] Remember since variable names are a form of internal documentation it should be somewhat self-evident of what the purpose of the variable is. However as you can see specifying the type of temperature is meaningful and useful information.