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
Olmo 3 Release Provides Full Transparency Into Model Development and Training
The Allen Institute for AI has unveiled Olmo 3, an open-source language model family that empowers developers with full access to the model lifecycle, from training datasets to checkpoints. Featuring reasoning-focused variants and robust tools for post-training modifications, Olmo 3 promotes transparency, experimentation, and community collaboration, driving innovations in AI.
By Robert KrzaczyńskiNexla Launches Express: A Conversational Platform for AI Data Engineering
Nexla recently introduced Express, a conversational data engineering platform designed to dramatically lower the barrier for building data pipelines for AI applications.
By Craig RisiCloudflare Global Outage Traced to Internal Database Change
Cloudflare’s recent global outage, linked to a database update, caused widespread disruption and highlighted the risks of single-vendor reliance. While service was restored, the incident sparked discussions on the importance of multi-vendor strategies in tech. Cloudflare's CEO vowed to enhance system resilience, emphasizing that outages can impact even the largest providers.
By Steef-Jan WiggersGrafana Unveils Smarter Logs, an MCP Server, and TraceQL Upgrades in Latest Releases
Grafana Labs has published major updates across two of its core observability products: Grafana 12.3, and Grafana Tempo 2.9. The two releases have distinct improvements in monitoring, logs, and tracing for Grafana users.
By Matt SaundersValkey 9.0 Introduces Multi-Database Clustering, Atomic Slot Migration, and Major Performance Gains
The Linux Foundation has announced the general availability of Valkey 9.0, the open-source in-memory storage solution developed as a successor to Redis. The latest major version introduces atomic slot migrations, hash field expiration, and full support for numbered databases in cluster mode, enabling scaling to 2,000 nodes and achieving over 1 billion requests per second.
By Renato Losio
© 2025 Created by Michael Levin.
Powered by
