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: 150
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
QCon London 2026: Introducing Tansu.io — Rethinking Kafka for Lean Operations
Peter Morgan introduced Tansu at QCon London, an open-source, Kafka-compatible, stateless, leaderless broker that scales to zero, with pluggable storage (S3, SQLite, Postgres), broker-side schema validation, and direct writes to Iceberg and Delta Lake. Written in Rust, it uses 20MB of RAM and starts in 10 milliseconds.
By Steef-Jan WiggersSonatype Launches Guide to Enhance Safety in AI-Assisted Code Generation
Sonatype Guide is a real-time guardrail system that sits between AI coding tools and the open-source ecosystem, ensuring AI-generated code uses safe, valid, and maintainable dependencies.
By Sergio De SimonePresentation: Platform Engineering as a Practice of Sociotechnical Excellence
Lesley Cordero discusses platform engineering as a practice for driving sociotechnical change and organizational sustainability. She explains the "pendulum of tension" between developer experience and reliability, emphasizing that architectural patterns must solve for organizational complexity. She shares a leadership framework for moving from reactive heroism to proactive stewardship.
By Lesley CorderoStripe Engineers Deploy Minions, Autonomous Agents Producing Thousands of Pull Requests Weekly
Stripe engineers describe Minions, autonomous coding agents generating over 1,300 pull requests per week. Tasks can originate from Slack, bug reports, or feature requests. Using LLMs, blueprints, and CI/CD pipelines, Minions produce production-ready changes while maintaining reliability and human review.
By Leela KumiliHarness Reimagines Artifact Management for DevSecOps with New Artifact Registry
Harness has announced the general availability of Harness Artifact Registry, a platform capability designed to simplify how engineering teams store, secure, and govern software artifacts within modern DevSecOps pipelines.
By Craig Risi
© 2026 Created by Michael Levin.
Powered by
