documentation, reusable code, and toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017...
TRANSCRIPT
![Page 1: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/1.jpg)
Documentation, Reusable Code, and Tooling
June 30, 2017
![Page 2: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/2.jpg)
Reading Quiz
![Page 3: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/3.jpg)
What is javadoc?A. Improved, multilingual documentation in Java8
B. A system for generating documentation based on code comments
C. A Java 8 feature to access your documentation at runtime
D. A system for generating code based on documentation
![Page 4: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/4.jpg)
Which is a reason for using Javadoc?
A. It makes it easier to keep your documentation in sync with your code comments
B. It makes it easier to keep your code comments in sync with your program's functionality
C. It makes it easier to type your code comments
D. It ensures users of your code will read your documentation
![Page 5: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/5.jpg)
Which is not an issue when building reusable, cross platform code?
A. Different conventions for line endings
B. Using `Runtime.exec` to call subprocesses / other programs
C. Architectural differences in the JVM
D. Hardcoded path names in programs
![Page 6: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/6.jpg)
Using Java naming conventions, what is a good method name?
A. THIS_ONE_RIGHT_HERE()
B. this_second_option_here()
C. thirdOptionCouldBeRight()
D. FourthOptionOfCourseDuh()
![Page 7: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/7.jpg)
Using Java naming conventions, what is THIS_THING_HERE probably?
A. a "static final" property (ie a constant)
B. a private method
C. a nested class
D. a static constructor
![Page 8: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/8.jpg)
Done!
![Page 9: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/9.jpg)
The Plan• One more note on Lambda
• Writing reusable libraries
• Javadoc
• Checkstyle
• Pmd
• Rules for libraries
• Homework 4
![Page 10: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/10.jpg)
Javadoc
![Page 11: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/11.jpg)
The Problem• Two types of documentation
• Implementation description (ex, code comments)
• Usage description (ex PDF, HTML, etc)
• Problematic
• Typing documentation is tedious (so less documenting)
• More things to keep in sync (can introduce and security hazards)
![Page 12: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/12.jpg)
Javadoc Solution
• A standard for commenting Javacode
• A tool to convert those comments into easer-to-read comments
• Write comments once, read wherever
![Page 13: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/13.jpg)
Javadoc Example/** * Class for demonstrating javadoc */public class JavadocExample { /** * An example of a method name * * <p>Here is a longer description of what this does. * * @param input boolean a true/false input to the method. * * @return String A string version of the boolean value. * * @throws ExceptionName An exception that gets thrown * * @see Some other method or thing to look at */ public String example(boolean input) { }}
![Page 14: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/14.jpg)
javadoc/RamonesFacts.java –>
![Page 15: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/15.jpg)
CheckStyle
![Page 16: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/16.jpg)
Problem
• Code is read more than written
• English (and other languages) have standards to ease readability
• We can do the same in Java to reduce errors
![Page 17: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/17.jpg)
Code Standard Example
THEROMANSWROTELATINALLINUPPERCASEWITH
NOWORDBREAKSORPUNCTUATION
Douglas Crockford - Programming Style & Your Brain
![Page 18: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/18.jpg)
checkstyle/Style.java –>
![Page 19: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/19.jpg)
![Page 20: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/20.jpg)
Coding Standards Help
• Google's https://google.github.io/styleguide/javaguide.html
• Oracle's (outdated) http://www.oracle.com/technetwork/java/codeconvtoc-136057.html
![Page 21: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/21.jpg)
Example Rules• Always indent with the block
• Spaces over tabs (and just two of them!)
• Curlies go on the same line
• Spaces around operators
• Variable naming conventions
• Don't fall through in "switch" statements
![Page 22: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/22.jpg)
checkstyle/Style.java –>
![Page 23: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/23.jpg)
PMD• Checks more than formatting
• Complicated functions
• Unused variables
• Unused imports
• Dead code
![Page 24: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/24.jpg)
Writing Libraries
![Page 25: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/25.jpg)
Libraries are "different"
• Provide functionality instead of using it
• Shared across projects
• General intent, instead of specific
• Main - Application, Library - Everything else
![Page 26: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/26.jpg)
Goals for Libraries• Be general
• Each library should have a single theme
• Each class should have a specific purpose
• Inform application about errors
• Never die / crash / dump stack / etc
![Page 27: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/27.jpg)
Goals Continued
• Hide as much as possible from the application
• Private properties
• Minimally visible methods, classes
![Page 28: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/28.jpg)
library/{Emojifier, Main}.java –>
![Page 29: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/29.jpg)
Where Should it Go? Application or Library?
• Error messages
• System.exit / status codes
• Documentation
• Defining exceptions
• User interface definition
• Text for user
![Page 30: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/30.jpg)
☕
![Page 31: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/31.jpg)
JSON?
A. I've used it a lot
B. I know what it is, but haven't used it
C. I've heard of it, but don't really know what it is
D. I've never heard of it
![Page 32: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/32.jpg)
YAML?
A. I've used it a lot
B. I know what it is, but haven't used it
C. I've heard of it, but don't really know what it is
D. I've never heard of it
![Page 33: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/33.jpg)
XML?
A. I've used it a lot
B. I know what it is, but haven't used it
C. I've heard of it, but don't really know what it is
D. I've never heard of it
![Page 34: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/34.jpg)
CSV?
A. I've used it a lot
B. I know what it is, but haven't used it
C. I've heard of it, but don't really know what it is
D. I've never heard of it
![Page 35: Documentation, Reusable Code, and Toolingpsnyder/cs342-summer2017/assets/slides/2… · 30/06/2017 · A Java 8 feature to access your documentation at runtime D. A system for generating](https://reader034.vdocument.in/reader034/viewer/2022050313/5f75e94678fe470ed9218cfe/html5/thumbnails/35.jpg)
Homework 4
• Comandline tool for playing with JSON data
• Data from city of Chicago https://data.cityofchicago.org/Transportation/Red-Light-Camera-Violations/spqx-js37
• No loops!