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 Token-Oriented Object Notation (TOON) Hopes to Cut LLM Costs by Reducing Token Consumption
The recently released Token-Oriented Object Notation (TOON) aims to be a schema-aware alternative to JSON that significantly reduces token consumption at a similar level of accuracy. While the existence and importance of token saved depend on the data shape. some benchmarks show TOON may use in some cases 40% fewer tokens than JSON, possibly resulting in LLM and inference cost savings.
By Bruno CouriolOlmo 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 Saunders
© 2025 Created by Michael Levin.
Powered by
