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: 153
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
Vercel Releases Open Agents to Support Background AI Coding Workflows
Vercel has launched Open Agents, an open-source app that enables the creation and execution of background coding agents. It provides a complete stack for developers to run independent coding workflows without relying on local machines.
By Robert KrzaczyńskiArticle: The DPoP Storage Paradox: Why Browser-Based Proof-of-Possession Remains an Unsolved Problem
DPoP closes a real gap in OAuth 2.0. Sender-constrained tokens are a meaningful upgrade over bearer tokens for any client that can implement them. But RFC 9449's silence on browser key storage creates the need for an architectural decision that each team must confront deliberately — there is no safe default that works everywhere.
By Dhruv AgnihotriNetflix Scales "Human Infrastructure" to Manage Global Live Operations
Netflix has introduced a "human infrastructure" layer to manage live broadcasts at scale. Using a low-latency "telemetry hot path" and a Live Operations Centre, the company now balances automated scaling with human oversight. This shift, which mirrors strategies at AWS and Disney+, focuses on maintaining reliability through expert intervention during high-concurrency global events.
By Mark SilvesterDBmaestro MCP Server Puts Natural Language in Control of Database Pipelines
DBmaestro has launched an MCP server that connects AI agents and enterprise copilots to its database DevOps platform, allowing teams to issue natural language commands that trigger real, governed platform workflows. The MCP server, announced on 7 April 2026, allows DBAs to expose DBmaestro's release automation, source control, CI/CD orchestration, and compliance capabilities through MCP.
By Matt SaundersVoidZero’s Experimental Oxc Angular Compiler with Up to 20x Faster Build Performance
VoidZero has released an experimental Angular compiler in Rust, promising improved build performance compared to Angular CLI. Benchmarks indicate it is up to 6.4x faster than Angular CLI, especially for larger applications. Developed over two months with AI collaboration, it integrates with Vite and offers significant reductions in build time. The initiative is for research purposes only.
By Daniel Curtis
© 2026 Created by Michael Levin.
Powered by
