Codetown
Codetown ::: a software developer's community
Documentation standards or guidelines?
Does anyone care to share their suggestions for documentation?
I'm asking because I recently had to change a program I wrote more than five years ago. I'd always thought that I've done a good job of documentation. But going through it was difficult. It WAS pulling apart an Excel in CSV format created and saved off by humans, so there was a lot of exception handling. But still . . . .
- Miek
Views: 140
Replies to This Discussion
-
Permalink Reply by Adam Davis on
-
Generally I only put javadocs on public methods, especially ones that are used a lot. I use code comments sometimes, but generally if the code is hard to understand I take that as a "smell" that means you need to break down the code into more methods, refactor, or think about better naming.
Happy 10th year, JCertif!
Notes
Welcome to Codetown!
Codetown is a social network. It's got blogs, forums, groups, personal pages and more! You might think of Codetown as a funky camper van with lots of compartments for your stuff and a great multimedia system, too! Best of all, Codetown has room for all of your friends.
Created by Michael Levin Dec 18, 2008 at 6:56pm. Last updated by Michael Levin May 4, 2018.
Looking for Jobs or Staff?
Check out the Codetown Jobs group.
InfoQ Reading List
Sauce Labs Launches AI Tool for Faster Test Analysis
Sauce Labs has launched Sauce AI for Insights, an AI-driven tool that accelerates test analysis by providing natural-language explanations, visual summaries and faster root cause detection. The company claims that it reduces debugging time, improves release readiness, and addresses the growing complexity of test data.
By Mark SilvesterGoogle Ships Angular 21: Signal Forms, Zoneless Migration, and AI-First Tooling
Angular 21 introduces groundbreaking advancements in web development, featuring Signal Forms for enhanced composability, zoneless change detection for streamlined performance, and AI-driven tools for improved developer experiences. This release emphasizes stability while optimizing reactivity and enabling smoother migrations, making it a game-changer for enterprise applications.
By Daniel Curtisgroundcover Takes Aim at Datadog with Observability Migration Tool
Observability platform company groundcover has launched a new migration tool to help organisations move their observability stacks from other vendors (such as Datadog) to its own platform. The company is claiming that organisations can migrate metrics, dashboards and monitors with full automation, and without needing any downtime nor consultants.
By Matt SaundersJava News Roundup: Liberica JDK, Jakarta EE, Open Liberty, Quarkus, JDKUpdater, OpenXava, Gradle
This week's Java roundup for November 17th, 2025, features news highlighting: an update on Jakarta EE 12; patch set updates for Liberica JDK; the December 2025 beta release of Open Liberty; and maintenance releases of Quarkus, JobRunr, OpenXava, JDKUpdater and Gradle.
By Michael RedlichPresentation: Humans in the Loop: Engineering Leadership in a Chaotic Industry
Michelle Brush discusses engineering leadership in the age of AI/ML and automation. She explains how the Jevons Paradox will create massive software demand, but the Ironies of Automation will make the remaining engineering job harder. She shares 4 skills for success: Systems Thinking, Non-Abstract System Design, Reliability Engineering, and Complexity Theory, stressing the need for junior talent.
By Michelle Brush
© 2025 Created by Michael Levin.
Powered by
