About 2 hours
Software engineers frequently reference a language’s or a framework’s documentation to understand how to use some part of that technology. It’s therefore important to know how documentation is intended to help you, and also how to read it effectively and efficiently.
You will someday want to write documentation for a project you’re working on in order to tell or show others how to use the project.
This is such an important topic in software development that many IDE companies provide languages specific extensions to help incorporate and standardize documentation in your code. For example Apple provides this support for Swift in Xcode https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/SymbolDocumentation.html. For JavaScript the Mozilla organization (originally Netscape) created the industry standard JSDoc https://en.wikipedia.org/wiki/JSDoc supported by many IDEs including Microsoft’s VSCode.
Participants will be able to:
Make sure your comments will make sense to someone with little context for what you were trying to do at the time you wrote the code. This could be a teammate or even your future self!
Comments should document the present and occasionally the future, but they should not be used to describe history. That’s what version control is for (we’ll learn about version control soon).
Don’t use bad words in comments.
“I’ll just add comments to as much of my code as possible so there will be no confusion later.” This is actually not a good practice. Your variable names and function names should be so descriptive that comments would be redundant. Use comments only to explain things that are not easily apparent by reading the code.
Via instructor-led Group Practice.
Look at this JavaScript code snippet together and talk through it line-by-line. Change some of the variable names and function names to make them more descriptive. Add/remove comments where appropriate.
Find the JavaScript documentation online.
Locate the entry for the .concat() array method. What does it do? Open a new file in REPL.it and use the .concat() method correctly on an example of your choosing.
Locate the entry for the .fill() array method. What does it do? Open a new file in REPL.it and use the .fill() method correctly on an example of your choosing.
Locate the entry for the .reverse() array method. What does it do? Open a new file in REPL.it and use the .reverse() method correctly on an example of your choosing.
Locate the entry for a string method of your choice. What does it do? Open a new file in REPL.it and use the method correctly on an example you made up.
Instructor asks for a volunteer to come up to the board and write out a proper implementation of one of the array methods studied during the Independent Practice. Classmates can assist if necessary. Anyone who discovered more methods during the Challenge section may also share those with the class.