What is our template for code documentation?

[phuanh004]

Can you change the title/ description for this issue? (Like what is the question?)

[nsyousef]

So I know in PA's we are usually expected to have file headers in each file with a bunch of information about the PA, such as the author, who people worked with, etc. We would also need class and function headers. We also probably need comments so others can understand our code.

I was under the impression that documentation is supposed to make it easy for others to understand our code (e.g. the TA's, theoretical new members to our team). So my guess is it probably mostly entails commenting our code and including headers and things like that. It might also refer to writing things like specs, diagramming our app before we code, and other forms of planning the design of our app before we actually code it up. I don't know if we necessarily need much else other than that, although if you all think of something else that I forgot about, feel free to list it here.

[nsyousef]

For example, for each function we write, we could have a header saying what it is intended to do, what types of input it is expecting, what types of output it is expecting, any conditions that must be met before calling the function, etc. Then, in the function, we could have comments to make the code easier to understand. I don't know if we are doing any object oriented programming, but if we are, for each class we could perhaps give a brief overview of the functions and fields an object of that class would contain, and how they are intended to be used. For file headers, we could perhaps just describe what the file does. We probably will only have one HTML, one CSS, and one Javascript file so we can probably just put a basic description. File headers might be more useful when you have a bunch of different files and you need to keep track of the purpose of each one.

[fnriv]

i agree with that- would this be a good function template? it's based on other cse templates:

• describe function and any important cases
• @param to list parameters (one param per line)
• @return to list possible outputs

then comment in the code for any important edge cases

[nsyousef]

That would probably be fine. Professor Powell hasn't really given us much of a standard for how he expects documentation to look, so it could be he expects it to be like it was in other CSE classes. The template you have put there seems to meet that standard, so I think for now we can use that.

[phuanh004]

i agree with that- would this be a good function template? it's based on other cse templates:

• describe function and any important cases
• @param to list parameters (one param per line)
• @return to list possible outputs

then comment in the code for any important edge cases

Agree! Reference: https://jsdoc.app/about-getting-started.html