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: 151
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
Anthropic Paper Examines Behavioral Impact of Emotion-Like Mechanisms in LLMs
A recent paper from Anthropic examines how large language models internally represent concepts related to emotions and how these representations influence behavior. The work is part of the company’s interpretability research and focuses on analyzing internal activations in Claude Sonnet 4.5 to understand the mechanisms behind model responses better.
By Robert KrzaczyńskiPresentation: Platform Engineering: Lessons from the Rise and Fall of eBay Velocity
Randy Shoup discusses the "Velocity Initiative," a transformation that doubled engineering productivity and modernized eBay’s DORA metrics. He shares the technical playbook used to scale 4,500 services while explaining why even elite engineering execution can’t save a company hampered by waterfall planning, risk aversion, and a "pathological" culture of fear.
By Randy ShoupArticle: Beyond One-Click: Designing an Enterprise-Grade Observability Extension for Docker
Docker Extensions boost developer speed but create a "visibility gap" by isolating telemetry. To meet enterprise needs, extensions must act as bridges to centralized platforms. This article details how to use OpenTelemetry, policy-as-code, and encryption to build secure pipelines. Learn to balance developer productivity with the governance required for scalable, compliant observability.
By Pragya KeshapAirbnb Migrates High-Volume Metrics Pipeline to OpenTelemetry
Airbnb's observability engineering team has published details of a large-scale migration away from StatsD and a proprietary Veneur-based aggregation pipeline toward a modern, open-source metrics stack built on OpenTelemetry Protocol (OTLP), the OpenTelemetry Collector, and VictoriaMetrics' vmagent. The resulting system now ingests over 100 million samples per second in production.
By Claudio MasoloGoogle Released Gemma 4 with a Focus On Local-First, On-Device AI Inference
With the release of Gemma 4, Google aims to enable local, agentic AI for Android development through a family of models designed to support the entire software lifecycle, from coding to production.
By Sergio De Simone
© 2026 Created by Michael Levin.
Powered by
