Week 03 Day 4: JavaDocs & Documentation

<style> @import url('https://fonts.googleapis.com/css2?family=Montserrat:wght@400;600&family=Lato:wght@400;700&display=swap'); :root { --red: #bf616a; --orange: #cb6343; --gold: #c3a364; --green: #719155; --blue: #556591; --purple: #85577c; /* Font families */ --header-font: 'Montserrat', sans-serif; --body-font: 'Lato', sans-serif; } /* Typography */ h1, h2, h3, h4, h5, h6 { font-family: var(--header-font) !important; font-weight: 600 !important; } .reveal p, .reveal ul, .reveal ol, .reveal li { font-family: var(--body-font) !important; font-size: 0.9em !important; } /* Existing color styles */ h1 { font-size: 1.7em !important; color: var(--orange) !important; } /* orange for main headers */ h2 { font-size: 1.4em !important; color: var(--orange) !important; } /* orange for sub headers */ h3 { font-size: 1.2em !important; color: var(--blue) !important; } /* blue for tertiary headers */ /* Code blocks */ .reveal pre { font-size: 0.75em !important; line-height: 1.3 !important; } .reveal code { font-size: 0.9em !important; } /* List items in code examples */ .reveal pre + ul, .reveal pre + ol { font-size: 0.85em !important; } /* Notes and additional text */ .current, .future { font-size: 0.9em !important; color: var(--green); background: rgba(113, 145, 85, 0.1); padding: 10px; border-radius: 5px; font-family: var(--body-font); } .future { color: var(--purple); background: rgba(133, 87, 124, 0.1); } /* Fragment text */ .reveal .fragment { font-size: 0.9em !important; } .flex-container { display: flex; justify-content: space-between; text-align: left; font-family: var(--body-font); } .flex-item { flex: 1; padding: 0 20px; } .flex-item:not(:first-child) { border-left: 1px solid #ccc; } /* Keep code in monospace */ .reveal pre, .reveal code { font-family: monospace !important; } </style>   # Mid-Day Menti 🌥️  ![image](https://hackmd.io/_uploads/rys9_sDFye.png) Note: Question: "What words come to mind when you think about code documentation?" Expected responses might include: - comments - confusing - necessary - boring - helpful - outdated - missing - unclear Use these responses to: 1. Acknowledge documentation pain points 2. Highlight why standardized documentation (JavaDocs) helps 3. Show how good documentation addresses their concerns 4. Lead into the importance of professional documentation practices ---  # Regex Review Quiz! 🎯  Regex Rumble Menti Quiz! Note: - Fun quiz to test regex knowledge from Jam03 - Use results to reinforce regex concepts - Connect to their Jam03 exercises - Clear up any confusion before moving to JavaDocs ---  # JavaDocs ### Why Documentation Matters 📚 Note: Welcome to our discussion about JavaDocs and professional code documentation! ---  ## <span style="color: #cb6343;">Code Tells How, Comments Tell Why</span> <div class="fragment fade-up">- Documentation is part of your code's contract</div> <div class="fragment fade-up">- Future you will need to understand your code</div> <div class="fragment fade-up">- Other developers rely on your documentation</div> <div class="fragment fade-up">- Good docs = Better collaboration!</div> Note: - Emphasize that documentation is communication - Point out that they'll read their own code later - Documentation is a professional responsibility ---  ## What Makes Good Documentation? 🤔 <div class="fragment fade-right">- Clear and concise</div> <div class="fragment fade-right">- Explains the why, not just the what</div> <div class="fragment fade-right">- Follows standard formats</div> <div class="fragment fade-right">- Stays up-to-date with code</div> <div class="fragment fade-right">- Helps others use your code</div> Note: Just like good writing follows grammar rules ---  ## Meet JavaDocs! ✨ <div class="fragment"> Your new best friend for: - Documenting classes and methods - Generating professional documentation - Following industry standards - Building maintainable code </div> Note: - Jam03 will help them practice JavaDocs - Point out that many companies require JavaDocs - Show examples of professional JavaDoc sites ---  ## JavaDoc Components - Description 📝 <div class="fragment fade-up"> <h3>The Main Documentation Text</h3> ```java /** * Converts a base-3 number to decimal. * This method validates input and handles the conversion process. */ ``` - First line is a concise summary - Additional lines provide more detail - Describes the "what" and "why" </div> Note: Start with the most basic part - the description ---  ## JavaDoc Components - Method Tags 🏷️ <div class="fragment fade-up"> <h3>Core Method Documentation</h3> ```java /** * Converts a base-3 number to decimal. * * @param input the base-3 number to convert * @return the decimal value * @throws IllegalArgumentException if input is invalid */ ``` - `@param` - documents parameters - `@return` - describes the return value - `@throws` - lists possible exceptions </div> Note: - These tags document method behavior - Order matters: params, return, throws - Be specific about parameter purposes - Always document exceptions ---  ## JavaDoc Components - Attribution Tags 📝 <div class="fragment fade-up"> <h3>Required Attribution</h3> ```java /** * Implementation of base-3 to decimal conversion. * * @author Lily Romano * @cite Based on algorithm from Introduction to Algorithms, * Cormen et al., Chapter 2.3 */ ``` - `@author` - identifies code author(s) - `@cite` - credits external sources/references </div> Note: - Both tags are required in our course - @author shows who's responsible - @cite prevents plagiarism - Multi-line citations are okay - Always cite external sources ---  ## Putting It All Together <div class="fragment fade-up"> <h3>Complete JavaDoc Example</h3> <div style="font-size: 0.7em;"> ```java [1-15|1-3|5|6|7|8|9-10|12-15] /** * Converts a base-3 number to decimal. * This method validates input and handles the conversion process. * * @param input the base-3 number to convert * @return the decimal value * @throws IllegalArgumentException if input is invalid * @author Your Name * @cite Based on conversion algorithm discussed in * CSCI205 Week 3 Lecture * * Example: * convert("101") returns 10 (1*9 + 0*3 + 1*1) * convert("21") returns 7 (2*3 + 1*1) */ public static int convert(String input) ``` </div> </div> Note: - Show how all components work together - Highlight the flow from description to details - Point out how each part serves a purpose --- ## IntelliJ Helps! 🛠️ - Type `/**` and press Enter - Generates JavaDoc template - Adds parameter tags - Adds return tag if needed - Documentation preview - Hover over method name - See formatted documentation - Quick validation Note: Let your IDE help you write good documentation! ---  # This Week's Challenge 💪 <div class="fragment current" style="margin-bottom: 30px;"> <h2 style="color: var(--blue) !important; font-size: 1.5em !important;">THIS WEEK (ALL BONUS!):</h2> - Add JavaDocs to your Jam03 code - Start building good documentation habits - Practice with IntelliJ's tools </div> <div class="fragment future"> <h2 style="color: var(--purple) !important; font-size: 1.5em !important;">NEXT WEEK:</h2> - Documentation will be part of your grade - JavaDocs required for public methods - Quality of documentation matters </div> Note: - Emphasize that this week is for learning - Show how to use IntelliJ's documentation tools - Demonstrate checking JavaDoc formatting --- ## Coming Soon: Checkstyle Requirements 🔍 <div class="fragment fade-up"> <h3>Required JavaDocs (WARNING)</h3> - All public methods over 2 lines long - All protected/public classes and interfaces - Exception: Methods with @Override or @Test </div> <div class="fragment fade-up"> <h3>Tag Requirements</h3> - Specific order: @param, @return, @throws, @deprecated - All @-tags must have descriptions - Tags must be in valid locations (ERROR) </div> Note: - These will be enforced by checkstyle - WARNINGs affect your grade - ERRORs must be fixed to submit - Start practicing now while it's bonus points --- ## Checkstyle Style Guidelines 📝 <div class="fragment fade-up"> <h3>Example of Valid Documentation</h3> ```java /** * First sentence is a clear summary. * Additional details in following lines. * * @param input description required * @return description required * @throws Exception describe when/why */ ``` - Summary sentence must be clear and complete - Empty line before @-tags - Each @-tag needs meaningful description - Order matters! </div> Note: - Show this example when writing docs - Common mistakes to avoid: - Missing parameter descriptions - Unclear summary sentences - Wrong tag order - No empty line before tags --- ## Why These Standards? 🤔 <div class="fragment fade-up"> <h3>Industry Standard</h3> - Used across Java ecosystem - Required for library development - Millions of projects worldwide </div> <div class="fragment fade-up"> <h3>Why Companies Care</h3> - Reduces onboarding time - Improves code maintenance - Facilitates collaboration </div> Note: - Our JavaDoc standards match industry practices - Many major libraries use these standards - Documentation is a professional requirement --- ## Key Takeaways 🎯 1. Documentation is part of your code 2. JavaDocs are the professional standard 3. Use IntelliJ's documentation tools 4. Build good habits early 5. Clear docs = Professional code ---  # Questions? 🤔 Note: - Ask if anyone has tried JavaDocs yet - See if there are any confusing tags - Check if IDE setup worked for everyone --- ## Resources - Oracle JavaDoc Guide - IntelliJ Documentation - Example JavaDoc Sites: - Java API Documentation - Apache Commons - Spring Framework ---  # Course Schedule ## 📅 <div style="display: flex; justify-content: center; align-items: center; min-height: 350px;"> <iframe src="https://docs.google.com/spreadsheets/d/e/2PACX-1vQKLFtWY5ICMBgFPkwhYFfY4f0xofHDTn_8G866v_AvbrllWZZLoDtzI-FZgMyHn8en9fs6MeOwW2WJ/pubhtml?single=true&gid=505611070&widget=false&chrome=false&headers=false&range=A1:G10&center=true" width="525" height="350" frameborder="0"></iframe> </div> Note: Review upcoming deadlines and next week's topics