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: 139
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
New IBM Granite 4 Models to Reduce AI Costs with Inference-Efficient Hybrid Mamba-2 Architecture
IBM recently announced the Granite 4.0 family of small language models. The model family aims to deliver faster speeds and significantly lower operational costs at acceptable accuracy vs. larger models. Granite 4.0 features a new hybrid Mamba/transformer architecture that largely reduces memory requirements, enabling Granite to run on significantly cheaper GPUs and at significantly reduced costs.
By Bruno CouriolJava News Roundup: Spring Framework 7.0, Spring Data, Spring AI, Payara Platform, OpenJDK, JobRunr
This week's Java roundup for November 10th, 2025, features news highlighting: OpenJDK JEPs targeted for JDK 26; the GA release of Spring Framework 7.0; point releases of Spring Data, Spring AI, JobRunr and Jox; the November 2025 edition of Payara Platform; the fifth release candidate of Maven 4.0; and a maintenance release of Micronaut.
By Michael RedlichKubeCon NA 2025 - Erica Hughberg and Alexa Griffith on Tools for the Age of GenAI
Generative AI technologies need to support new workloads, traffic patterns, and infrastructure demands and require a new set of tools for the age of GenAI. Erica Hughberg from Tetrate and Alexa Griffith from Bloomberg spoke last week at KubeCon + CloudNativeCon North America 2025 Conference about what it takes to build GenAI platforms capable of serving model inference at scale.
By Srini PenchikalaPresentation: AI-Driven Software Delivery: Leveraging Lean, ChOP & LLMs to Create More Effective Learning Experiences at QCon
Wes Reisz discusses an experiment to deliver a QCon certification using a Retrieval-Augmented Generation (RAG) architecture and supervised coding agents (Claude Sonnet/Cursor). He breaks down the 4-week serverless video transcription pipeline, RAG variations (hybrid, graph), and the process of structuring prompts for 95% AI-generated code.
By Wesley ReiszCode Arena Launches as a New Benchmark for Real-World AI Coding Performance
LMArena has launched Code Arena, a new evaluation platform that measures AI models' performance in building complete applications instead of just generating code snippets. It emphasizes agentic behavior, allowing models to plan, scaffold, iterate, and refine code within controlled environments that replicate actual development workflows.
By Robert Krzaczyński
© 2025 Created by Michael Levin.
Powered by
